svelte-plus

Imported from jjdubski/svelte-plus (AGENTS.md). Install upstream with npx skills add jjdubski/svelte-plus. Copyright stays with the author.

svelte-plus — Agent Guide

This is an interactive CLI scaffolding tool for Svelte 5 + SvelteKit projects. It wraps npx sv create, adds opinionated QoL features, and can also retrofit an existing Svelte project.

Quick start

npx svelte-plus my-app       # create new project
npx svelte-plus .             # retrofit existing Svelte project

Repo structure

Exact developer commands

Prettier config: useTabs: true, tabWidth: 4, singleQuote: true, trailingComma: "none", printWidth: 100. Markdown files override: tabWidth: 2, printWidth: 500, embeddedLanguageFormatting: "off".

ESLint flat config enforces no-unused-vars with _ prefix convention (argsIgnorePattern: '^_', varsIgnorePattern: '^_'). Test files get globals.vitest for vitest globals.

Node: engines >=18, CI uses 22.

How the CLI works

1. main({ appName }) routes to createNew() or addToExisting():

   • Existing Svelte project → addToExisting()
   • Non-existent dir → createNew()
   • Existing non-Svelte dir → cancels with exit 1
   • No appName → prompts for project directory, then same logic (also re-checks for existing Svelte project)

2. Prompt flow in getOptions():

   • svelte-plus setup mode: Default / Minimal / Custom (select subset of features)
   • Template (new projects): Minimal / Demo / Library
   • Type checking: TypeScript / JSDoc / None
   • Add-ons (multi-select): eslint, prettier, vitest, playwright, tailwindcss, sveltekit-adapter, drizzle, better-auth, mdsvex, paraglide, storybook, mcp
   • Addon sub-prompts:
     • vitest: unit testing, component testing (multi)
     • tailwindcss: typography, forms plugins (multi); then asks about shadcn-svelte setup
     • sveltekit-adapter: auto/node/static/vercel/cloudflare/ netlify; cloudflare gets Workers vs Pages
     • drizzle: database (postgresql/mysql/sqlite/d1) + client per database + optional docker-compose
     • better-auth: email/password, GitHub OAuth (multi)
     • paraglide: language tags (text), include demo (confirm)
     • mcp: IDE selection (claude-code, cursor, gemini, opencode, vscode, other) + setup (local/remote). When only opencode is selected, the setup prompt is skipped via the condition in sv add.
   • Package manager: none / npm / yarn / pnpm / bun / deno

3. createNew() flow:

   • npx sv create --template X --types Y --add '...' --no-install <dir>
   • Anything with option-specific args (vitest, tailwindcss, sveltekit-adapter, drizzle, better-auth, paraglide, mcp) uses formatters in ADDON_FORMATTERS.
   • Add-ons with no special formatter are passed as-is.
   • Storybook is deferred — excluded from sv create (via --no-add-ons fallback), runs as sv add storybook inside the project directory after creation.
   • Creates standalone vitest.config.* if vitest selected (sv create embeds vitest in vite.config.*; this gives users a discoverable config file).
   • Updates package.json with svelte-plus features (husky, lint-staged, lucide-svelte, fallow dep, stylelint, prettier-plugin-tailwindcss, scripts, etc.)
   • Writes config files (.prettierrc, .prettierignore, .env.example, src/app.css, CI workflows)
   • Post-setup: hooks, npm install, npx husky init, shadcn, playwright browsers, format

4. addToExisting() flow:

   • Runs npx sv add <addon> --no-git-check per addon
   • Falls back to npm install if sv add fails (eslint + eslint-plugin-svelte, prettier + plugins, vitest — each tracked in pendingDeps)
   • Same config file writing and post-setup as createNew()

Available add-ons (12)

CI workflows (5)

Committed in .github/workflows/ and also generated for new projects. Generated by writeTestWorkflow(), writeFallowWorkflow(), writeReviewdogWorkflow(), writeTriggerWorkflow(), and writeBuildWorkflow().

• test.yml — npm ci + npm test. Package-manager aware (uses correct cache key and frozen install). Supports workflow_dispatch, PR, push triggers. Includes pending check run management for dispatch-triggered runs.
• build.yml — npm ci + npm run build. Posts build failure as a PR comment and creates check run annotations from vite-plugin-svelte error output.
• fallow.yml — fallow-rs/fallow@v2 SARIF analysis with audit mode on PRs, full scan on push. Includes check run lifecycle and PR comment on findings.
• reviewdog.yml — 6 jobs: eslint, actionlint, markdownlint, shellcheck, stylelint, svelte-check + a full check job for push events. PR review on added lines; full check on push. Each job manages pending check runs for dispatch-triggered runs.
• trigger.yml — /workflow comment handler. Clears existing check runs on the PR, then dispatches all 4 workflows (test, fallow, reviewdog, build) in parallel via gh workflow run.

All 5 workflows share the same trigger pattern: workflow_dispatch, PR opened/ready_for_review, push to main. Draft PRs do not trigger CI — they need /workflow comment or ready_for_review event.

svelte-plus feature flags

In DEFAULT_SVELTE_PLUS_FEATURES:

• config-files — .prettierrc, .prettierignore, .env.example, app.css, test/build/trigger CI workflows
• husky — git hooks (pre-commit, pre-push)
• lint-staged — run linters on staged files
• lucide-svelte — icon library dep
• format-lint-scripts — add format/lint/lint:fix scripts to package.json
• install-deps — run package manager install
• fallow — static analysis dep + CI workflow
• reviewdog — reviewdog CI workflow + config + stylelint

Three setup modes: default (all features), minimal (config-files only), custom (pick subset).

Architecture notes

• buildAddonArgs() converts addon options to sv create --add arg strings. Each addon has a formatter in ADDON_FORMATTERS. When adding new addons, add a formatter and test it.
• runStep() / runCommandStep() — shared wrappers for spinner + logging. Heavy steps (listed in HEAVY_STEP_IDS) get the spinner immediately; others get a 2-second delay before showing it.
• writeHook() writes to .husky/<name>, chmod +x. Pre-commit runs lint:fix + npx lint-staged (lint-staged only if feature enabled); pre-push runs <pm> test --if-present.
• Storybook is deferred — not passed to sv create --add, runs via npx sv add storybook --no-git-check after project creation.
• Package manager agnostic — maps PKG_CMDS for npm/yarn/pnpm/bun/deno for dev/test commands, and PKG_MANAGER_CMDS for install commands.
• MCP addon onlyOpencode condition: When only opencode is selected as the IDE, the setup (local/remote) prompt is skipped, matching the sv add condition behavior.
• setupShadcn() — runs shadcn-svelte@latest init with --skip-preflight first; falls back to init without the flag. Skips if pkgManager is none (prevents hanging). If tailwindcss wasn't already added, adds it via sv add first with a fallback to npm install -D tailwindcss @tailwindcss/vite.
• applyFeatureDeps() — shared function that adds husky, lint-staged, lucide-svelte, fallow, stylelint, prettier-plugin-tailwindcss, and format/lint scripts to the project's package.json. Used by both createNew() and addToExisting().
• Generated .prettierrc has printWidth: 120 (the repo's own is 100), tailwindStylesheet: './src/app.css', includes prettier-plugin-svelte + prettier-plugin-tailwindcss, and has overrides for *.md (tabWidth: 2, printWidth: 500) and *.svelte (parser: svelte).
• Vitest config generation: When vitest is selected, a standalone vitest.config.* is created alongside the embedded config in vite.config.* for discoverability. Uses .ts or .js extension based on types setting.
• buildGithubWorkflow() / buildBuildWorkflow(): Generate workflow YAML adapted to the chosen package manager (cache key, frozen install command, dev/test scripts).

Testing quirks

• All child processes are mocked. Tests mock child_process (execSync) and @clack/prompts entirely. spawn is explicitly set to undefined in test mocks. No real binaries execute.
• Test helpers: tmpDir() creates temp dirs, fixture(name) resolves fixture paths, defaultOpts() / existingOpts() build option objects.
• Integration tests pre-create the project directory before calling createNew() (most tests) but verify it gets created for the "waits for project directory" test.
• Run npm test before opening a PR. Tests are fast (~2s) since they're fully mocked.
• vitest.config.js includes ['tests/**/*.test.js']. All unit and integration tests live in tests/.
• setupShadcn() tests mock both the primary init and the fallback init, verifying error output on double failure.

Husky hooks (this repo)

Current repo hooks:

• pre-commit: npm run lint:fix --if-present + npx lint-staged
• pre-push: npm test --if-present + npm run reviewdog --if-present

The generated hooks (in new projects) differ slightly: pre-push only runs <pm> test --if-present.

Gotchas

• bin/ binaries are committed but gitignored. The .gitignore patterns actionlint, reviewdog, shellcheck (no leading /) match the committed files in bin/ and also block new untracked copies elsewhere. Git-tracked files aren't affected by gitignore, so the binaries stay functional in the working tree.
• AGENTS.md is excluded from markdownlint (in both .reviewdog.yml and CI workflow). Any content here bypasses markdown linting, but this file also won't catch lint failures that other .md files would.
• .husky/.gitignore contains only _ (husky's internal shim directory). Don't let this look incomplete.
• ESLint _ prefix convention: unused function args and variables must be prefixed with _ to suppress lint errors.
• eslint.config.js ignores: node_modules/, .husky/, new-project/, docs/ — this is important when running eslint so it doesn't choke on test artifacts.