Playbook

Show how this repo is setup via step-by-step guild

✨ Key Features

• 🏗️ Type Safety - Full type-safety with strict type checking
• 📦 Bun - Fast, disk-efficient package management
• 🏃 Turborepo - High-performance build system
• 📝 Biome - Fast and consistent code style
• 🧪 Testing - Complete testing setup with Vitest
• 🚀 CI/CD - Ready-to-use GitHub Actions workflows

Base

Prerequisite

Install node and pnpm

[!NOTE] Since v16.13, Node.js is shipping Corepack for managing package managers.

brew install node
# This will automatically install pnpm on your system.
corepack enable pnpm

[!NOTE] You can pin the version of pnpm used on your project using the following command

cd ~/Developer/Work/SPA/spectacular
corepack use pnpm@latest-10

Install following CLI tools globally

• svelte CLI
• tsx to run TypeScript & ESM files from command-line. This is NOT React's TSX/JSX
• hasura-cli as GitOps tool for Hasura
• dotenv
• turbo
• vercel

pnpm add -g sv
pnpm add -g turbo
pnpm add -g @dotenv-run/cli
pnpm add -g vercel

Chrome Plugins

Install Chrome Plugins

• Svelte DevTools
• GraphQL Network Inspector

Create

# bun create svelte@latest spectacular && cd $_ && code .
bunx sv create --no-install --template minimal spectacular
# select `yes` for TypeScript, vitest, playwright, tailwindcss and paraglide
# select needed tailwindcss plugins (optional)
# paraglide: Which languages would you like to support?  en,es,de

Next steps:

1. git init && git add -A && git commit -m "chore(root): first commit" (optional)
2. pnpm run dev -- --open

In this Playbook, we will be using svelte-add to easily add and integrate 3rd party tools to this Svelte App.

Workspace

dotenv-run helps loading nested .env files in monorepo.

# pnpm add  -D dotenv-cli -w
pnpm add -D @dotenv-run/cli  -w

Testing

We will use vitest for Component (mocked) testing and Playwright for E2E tests (nothing is mocked).
Code coverage via c8 or istanbul.

svelte-add-vitest preset will add vitest to your SvelteKit project.

For examples checkout Svelte Component Test Recipes

TODO: switch to sveltest https://sveltest.dev/

# optional
bun i -O @vitest/ui

# install supported browsers
bunx playwright install

SEO

Meta Tags, OG

Svelte Meta Tags provides components designed to help you manage SEO for Svelte projects.

bun add -D svelte-meta-tags --filter "./apps/**"

Image Optimization

Svelte Images A toolbox of import directives for Vite that can transform your image at compile-time.

bun add -D @sveltejs/enhanced-img --filter "./apps/**"

Setup

import { defineConfig } from 'vite';
import { enhancedImages } from '@sveltejs/enhanced-img';

export default defineConfig({
  plugins: [enhancedImages()],
});

Usage

import Image from 'example.jpg?w=400&h=300&format=webp';

Dynamic OpenGraph images

docs, examples

bun add -D @ethercorps/sveltekit-og --filter "./apps/docs"

Release

changesets

working with changesets in turborepo

npx changeset init
bun add -D @changesets/changelog-github  -w

Web Analytics

Vercel Web Analytics

bun add -D @vercel/analytics --filter "./apps/**"

In your SvelteKit project's main +layout.svelte file, add the following <script>:

src/routes/+layout.svelte

<script>
  import { dev } from '$app/environment';
  import { inject } from '@vercel/analytics';
  inject({ mode: dev ? 'development' : 'production' });
</script>

Styling

We will be using TailwindCSS for system-wide styling.
Follow SvelteKit integration guide
Animation with tailwindcss-animate, usage example, Demo

Add and configure tailwindcss via svelte-add

bunx svelte-add@latest tailwindcss  --typography --daisyui
# NOTE: tailwindcss's forms plugin and daisyui wont work together
# also add other tailwind plugins and include them in `tailwind.config.cjs`
pnpm add --save-peer @tailwindcss/container-queries tailwindcss-animate tailwind-merge clsx --filter ./packages/tailwind-config
pnpm add --save-peer  flowbite-svelte flowbite-svelte-blocks flowbite-svelte-icons flowbite-typography --filter ./packages/tailwind-config
pnpm add -D @tailwindcss/container-queries tailwindcss-animate tailwind-merge --filter "./apps/**"
pnpm add -D flowbite-svelte flowbite-svelte-blocks flowbite-svelte-icons flowbite-typography --filter "./apps/**"

Install JetBrain's postcss plugin
Rename any files in your repo, with file extension postcss to pcss

cssnano

Also add cssnano plugin for postcss and include it in postcss.config.cjs for production env.

pnpm add -D cssnano

PostCSS Preset Env

PostCSS Preset Env lets you convert modern CSS into something most browsers can understand, determining the polyfills you need based on your targeted browsers or runtime environments.

Read: Use Future CSS Today and Watch: video

pnpm add -D postcss-preset-env

Add postcssPresetEnv plugin for postcss and include it in postcss.config.cjs.

UI Components

We will be using Flowbite its Svelte UI Components
Follow flowbite-svelte getting-started guild, install and configure tailwind.config.cjs

We will be using Flowbite icons via flowbite-svelte-icons Icon Components.

Use clsx in place of classnames utility lib for constructing className strings conditionally.

Flowbite Svelte Blocks: quickstart

# pnpm add -D flowbite flowbite-svelte tailwind-merge
# pnpm add -D flowbite-svelte-icons
pnpm add -D flowbite-svelte flowbite-svelte-blocks flowbite-svelte-icons
pnpm add -D clsx

Other optional UI Components

• DaisyUI
• headlessUI
• skeleton

I will be using both flowbite and daisyui for UI Components

pnpm add -D daisyui

Then add daisyUI to your tailwind.config.js files:

const config = {
  //...
  plugins: [typography,  ..., daisyui]
}

skeleton

pnpm add -D @skeletonlabs/skeleton

And follow skeleton specific sveltekit changes

shadcn-svelte

pnpm add -D tailwind-variants clsx tailwind-merge --filter "./apps/console3"
pnpm add -D mode-watcher --filter "./apps/web"

Util

Stores

pnpm add -D svelte-persisted-store --filter "./apps/console"

Bot Protection

Bot Protection for nhost-auth with Cloudflare Turnstile

pnpm add -D svelte-turnstile --filter "./apps/console"

UI Blocks

• Kometa UI Kit (Free) Blocks
• Tailblocks via tailblocks github
• Tailwind Components (Free)
• Flowbite Blocks via flowbite-svelte-blocks
• Konsta UI - is a free and open source mobile UI svelte components framework built with Tailwind CSS.

Tools

Prettier

Lets add prettier-plugin-tailwindcss

prettier-plugin-svelte has conflict with prettier-plugin-tailwindcss which is included during SvelteKit project creation.
To work around this, prettier-plugin-tailwindcss must be loaded last, meaning Prettier auto-loading needs to be disabled. You can do this by setting the pluginSearchDirs option to false and then listing each of your Prettier plugins in the plugins array:

pnpm add -D prettier-plugin-tailwindcss
pnpm add -D prettier-plugin-packagejson -w

// .prettierrc
{
  // ..
  "plugins": [
    "prettier-plugin-svelte",
    "prettier-plugin-organize-imports",
    "prettier-plugin-tailwindcss" // MUST come last
  ]
}

Docker

Added Dockerfile and GitHub actions.

Addons

Recommended

1. Headless Table
   1. Svelte Headless Table
   2. TanStack Table
2. A lightweight Svelte Action to make your elements draggable

# table library for Svelte
pnpm add -D svelte-headless-table  --filter "./apps/**"
#pnpm add -D @tanstack/svelte-table
# form library for Svelte
pnpm i -D sveltekit-superforms zod formsnap zod-form-data sveltekit-rate-limiter --filter "./apps/**"
# make any element draggable
pnpm add -D @neodrag/svelte --filter "./apps/**"
# to fetch, cache and update data
pnpm add -D @tanstack/svelte-query --filter "./apps/**"

Optional

view-transition

with sveltekit-view-transition

pnpm add -D sveltekit-view-transition@latest --filter "./apps/**"

Markdown CMS

bunx svelte-add@latest mdsvex

Time Distance

svelte-time-distance Display time distances in a human readable format.

pnpm add -D svelte-time-distance date-fns

Error Tracking

Sentry helps track errors in code.

bunx sentry/wizard@latest -i sveltekit

GraphQL

VS Code: install GraphQL.vscode-graphql VS Code plugin

use houdini as GraphQL Client. example

houdini cli docs

Houdini Plugins

• live-queries

pnpm add -D houdini graphql-ws

# bunx houdini init
bunx houdini@latest init --headers "x-hasura-admin-secret=<HASURA_GRAPHQL_ADMIN_SECRET>"

# To updated your local schema with latest from the graphql server, run:
# HINT: it will use `apiUrl` and `schemaPollHeaders` in `houdini.config.js`
cd apps/web
node_modules/.bin/houdini pull-schema

(Or) URQL. example

pnpm add -D @urql/svelte graphql
# TypeScript integration (optional)
# https://formidable.com/open-source/urql/docs/basics/typescript-integration/
pnpm add -D @graphql-codegen/cli @graphql-codegen/client-preset -w

OpenID Connect

Use Auth.js for Authentication

TODO: try jose as alternative to jsonwebtoken ?

pnpm add  -D @auth/core @auth/sveltekit @auth/hasura-adapter --filter "./apps/web"
# for custom encode and decode JWT.
# pnpm add jsonwebtoken
# pnpm add -D @types/jsonwebtoken
# https://github.com/auth0/node-jsonwebtoken/issues/655
pnpm add jose

# Hasura Auth.js Adopter
pnpm add  -D next-auth-hasura-adapter

Cookies

Set/Get/Remove cookies in browser (for server-side svelte already provide utils)

Forms

Custom form elements

pnpm add -D svelte-select

i18n

We switched to inlang's Paraglide JS for i18n

bunx @inlang/paraglide-js@latest init

Progressive Web Apps (PWA)

check example for reference.

# pnpm add -D @vite-pwa/sveltekit
pnpm add -D @vite-pwa/sveltekit @vite-pwa/assets-generator vite-plugin-pwa workbox-window --filter "./apps/console-fb"

add pwa-assets.config.ts to project root

AI

# add vercel AI core
pnpm add -D ai @ai-sdk/svelte --filter console
# add optional providers
pnpm add -D  @ai-sdk/openai @ai-sdk/azure chrome-ai ollama-ai-provider --filter console

Enable https (optional)

Step 1: install mkcert and initialize RootCA

brew install mkcert
mkcert -install # sudo is needed
# this will create root CA cert into: `mkcert -CAROOT` output
mkcert -CAROOT

Step 2: Configure vite to start with https

pnpm add -D  vite-plugin-mkcert

Update vite.config.ts

// vite.config.ts
import { defineConfig } from 'vite'
import mkcert from 'vite-plugin-mkcert';

const config: UserConfig = {
 server: {
   https: true,
   host: 'console.traefik.me'
 },
 plugins: [
  mkcert(),
 ]
};

export default config;

When server started for the first time with pnpm dev, it will create dev.key and dev.pem in ~/.vite-plugin-mkcert/certs

know issues: https://github.com/sveltejs/kit/issues/4362