Spectacular

Spectacular is a full-stack Turborepo template project with SvelteKit meta-framework all working in harmony and sharing packages.

Tech Stack

• Monorepo: Turborepo
• JS Framework: SvelteKit
• CSS: Tailwind CSS
• UI Components: tailwindcss based SkeletonUI, Shadcn and Flowbite
• Unit/Component testing: vitest
  • Testing Library
  • Svelte Testing Library
• API Mocking: Mock Service Worker
• Code Coverage c8
• End-to-End Testing: playwright
• GraphQL: Houdini & Hasura
• Authentication: Auth.js, nhost-auth
• PWA: Vite PWA
• Linter/Formatter: Biome

Features

• Responsive Design: Container queries
• Progressive Web Apps (PWAs):
  • Smart caching with Service Works
  • Re-engage customers with Push Notifications
  • Push Application Updates
  • Offline app with pglite
• Fonts and Image Optimization: edge caching, Lazy-loading images
• SEO Ready
  • Meta Tags and Json-LD with svelte-meta-tags
  • Dynamic OpenGraph images with sveltekit-og
  • Image Optimization with sveltejs/enhanced-img
• GraphQL: Houdini the disappearing GraphQL client for SvelteKit. and nHost as BaaS
  • Elevated Permissions
• Forms: Form handling with [superforms, source] and Validation with zod
• Error Handling:
  • Strongly Typed Error Handling with generic errors
  • FormData preprocessing with zodfd
• Themes: tailwindcss DarkMode switcher
• Deployment: Docker build and deployment serverless / k8s runtimes.
• Tables: svelte-headless-table
• Security: Use Auth.js when stable
• Vitebook or Storybook 7
• GraphQL Yoga API
• Documentation micro site with Astro
• Build Tools
  • Use Bob.Build for Smart Builds, Build Cache etc and Bob's github-actions
  • Use earthly.dev - Great for monorepos, Compatible with Every Language, Framework, and Build Tool
• Use sveltekit-og for Open Graph Image Generation
• Internationalization(i18n) with inlang Paraglide JS Adapter SvelteKit

Experementing

• Implement Changesets (link) with turborepo
• TAURI: Use Tauri with Skeleton for multi-platform.
• Charts with Unovis. Explore Gallery
• Feature Flags with Vercel Feature Flags and Vercel Toolbar

Setup

cd ~/Developer/Work/SPA
git clone https://github.com/xmlking/spectacular.git
cd spectacular && pnpm i
# (optional) playwright is required for end-to-end testing
bunx playwright install
# (optional) add git-commit-hooks
cog install-hook --all

Environment Variables

By default, the dev server (dev command) runs in development mode and the build command run in production mode.
This means when running turbo build, it will load the env variables from .env.production if there is one:
Use .env.local to override environment variables in .env (secrets like API keys) for local development.

Developing

Once you've cloned the project and installed dependencies with pnpm i, start a development server:

Start local Hasura

# stat all services in background and show logs
make up # for first time use `make boot` then `make up`
# this will start all services with default profile + services with `all` profile.
make up PROFILES=all
# verify status/health of services
make ps
# shotdown all services
make down
# DANGER: run this if you want to reset database and other persistent volumes
make teardown
# verify if docker `compose` getting correctly resolved application config from .env and .secrests files
make check
make check PROFILES=all,optional
# ssch to a container to debug
#make exec-<target>
make exec-hasura
make exec-auth

Start apps/console

turbo --filter=@spectacular/console dev

# or use `--log-order=stream` to disable TUI
turbo --filter=@spectacular/console --log-order=stream dev

# or start the server and open the app in a new browser tab
turbo --filter=@spectacular/console dev -- --open 

# run in debug mode
turbo --filter=@spectacular/console dev:debug

# run with a custom inline config
# inline environment variables has higher precedence than ones loaded from .env and .env.local files
PUBLIC_NHOST_GRAPHQL_URL=api.mycompany.com:443 turbo dev

Maintenance

Update

To update the packages to their latest versions in package.json

pnpm up --latest -r
pnpm audit --fix

Format

Format and lint code

turbo format
turbo format --filter=!'@spectacular/console'
turbo lint

Testing

Unit/Component Tests

turbo test

turbo test:ui
#Then, you can visit the Vitest UI at http://localhost:51204/__vitest__/.

# test coverage
turbo test:coverage

# updating Snapshots
bunx vitest -u

# test specific folder
bunx vitest apps/web/src/lib/utils
(or)
./node_modules/.bin/vitest run apps/web/src/lib/utils

E2E Tests

turbo test:e2e

Building

To create a production version of your app:

turbo build
# run build
turbo --filter=@spectacular/console... build
turbo --filter=@spectacular/console... --dry build
turbo --filter=@spectacular/console... --graph build

Run from the local build directory:

NODE_ENV=production \
PUBLIC_NHOST_GRAPHQL_URL=api.mycompany.com:443 \
node build

# (optional) pass ORIGIN when using `adapter-node` build
HOST=127.0.0.1 \
PORT=4000 \
ORIGIN=https://my.site \
node build

You can preview the production build with turbo preview --filter=@spectacular/console....

To deploy your app, you may need to install an adapter for your target environment.

Release

after checking-in all your changes, bump the VERSION and build the docker image.

# dry-run
cog bump --auto --dry-run
# this will bump version in package.json and create git tag and commit.
cog bump --auto

Libs

To build and publish libs

turbo build --filter=lib...
cd package
pnpm publish