VelaStack Patterns

The registry for VelaStack patterns.

Requirements

Patterns write SvelteKit 3 code only, and the package needs Node 22.22 or later (engines), the same floor as a vela project (SvelteKit 3 itself starts at 22.17; openworkflow 0.11 needs 22.22). A project with a svelte.config.*, or with options still nested under kit:, is refused with npx vela@^0.15 migrate sveltekit-3. Config edits go into the inline sveltekit({...}) call in vite.config.ts.

• Imports from src/lib use #lib (the "imports" entries in package.json) with sv's extension rules: #lib/server/db.js, #lib/components/ui/button/index.js, #lib/x.svelte.js for x.svelte.ts, while .svelte files keep their extension. The SvelteKit 2 alias is still recognised when reading existing imports, never written.
• Environment variables are read as named imports from $app/env/private / $app/env/public. A pattern that reads one declares it in src/env.ts (modifyEnvVars in src/runtime/env-vars.ts, creating the file when there is none) as optional, schema: (value) => value ?? '', so a build with an empty .env still passes. Existing entries are never changed; disable-* removes the names its enable-* declares.
• formsnap 2.1 is the first release whose superforms peer admits 3.x. Installing formsnap, or superforms into a project that has it, first moves a 3.0.0-next superforms pin to the release, raises a formsnap range below 2.1 and drops the "overrides": { "formsnap": … } entry earlier releases wrote for formsnap 2.0; otherwise npm stops with ERESOLVE or keeps the lockfile's formsnap 2.0. superforms and flash-message are installed with --save-exact.

Runtime

There's two modes this library can be used. One is in runtime, by the @velastack/cli. The VelaStack CLI uses Commander to get inputs from the CLI and then calls the pattern:

The CLI determines what existing features are in use and passes feature flags to the loadPattern() function. It also takes any additional wizard inputs from the CLI and passes the data as input.

const pattern = await registry.loadPattern("generate-form", {
  env: "runtime",
  argv: ["contact", "name:text", "email:email", "message:editor"],
  root: "/user/project",
  features: {
    auth: false,
    payments: false,
  },
  input: {},
});

Preview

The other way is for the velastack.dev/patterns website. Each pattern is available for browsing. Each pattern is loaded like this:

const pattern = await registry.loadPattern("generate-form", {
  env: "preview",
  argv: ["contact", "name:text", "email:email", "message:editor"],
});

In the runtime, @velastack/patterns loads libraries like pocketbase and ts-morph to make modifications to the user's project. This isn't possible in the preview environment, so these changes are mocked with stock output. Keeping this separation is important. Any libraries or node requirements must only be imported inside of generate.runtime.ts files.

Those dependencies are specified as devDependencies and also optionalDependencies for use with the CLI.

File Structure

For each pattern, generate.ts is the main generator. As much of the pattern as possible should be configured here. Libraries that can't be run in the preview environment are imported only in generate.runtime.ts, this async import is only called during the runtime.

However, we still need examples of what generate.runtime.ts outputs, so we have generate.preview.ts, containing a static version of what we'd typically get from the runtime.

Within each pattern, we have creates, modifies and preview-modifies directories.

Creates

The creates directory is directly copied into the target project. Each file is bundled into the library using import.meta.glob.

Modifies

The modifies directory contains scripts that modify the target project. Modifications use ts-morph when possible. Each modification should have an extensive test suite with fixtures/expect and fixtures/original to ensure that the modifications work across a wide range of project setups.

Modifiers call formatLikeSource(sf) (src/runtime/ts-morph-helpers.ts) rather than sf.formatText(), whose four-space default re-indents every line of a tab-indented file; a project without prettier has nothing to put that back. withInMemoryScript takes the shared indent off a <script> body before ts-morph sees it and puts it back afterwards, so an added import lines up with its neighbours.

Preview-Modifies

The preview-modifies directory is the mock modify output used only for previews. It's bundled in the same way as the creates directory.

Providers

A capability with several implementations (vela enable analytics --provider plausible|google|posthog) declares them on the pattern as providers: [{ id, label, env }], in prompt order. The CLI reads that list to prompt for a provider and validate --provider, and asks for each declared env key (blank allowed; a secret: true key, such as vela enable ai's API keys, is asked for without echo). Files for each provider live in providers/<id>/** and are bundled like creates; generate.ts picks the chosen set with resolveProvider(META, options) + providerCreates(raw, id) from src/core/providers.ts. resolveProvider reads input.provider, then --provider in argv; an unknown id is an InvalidArgumentError listing the known ones, a missing one is an error at runtime and the first provider in preview (the website loads patterns with argv only). Shared behaviour (the layout modifier, writing the env keys to .env with providerEnvEdits + suppliedProviderEnv) stays in the pattern's generate.runtime.ts. Providers are a separate dimension from variants.

Nothing records which provider a project chose. detectProviders(root) (exported, node-only) reads it back from the project, one id per capability ({ payments: "stripe" }). A caller passes the result to the pattern as options.providers; the integration harness does, and so does a CLI that knows about it. Each provider is found by its markers (a name declared in src/env.ts, an app-relative path, or a dependency), which default to its first env key; provider-markers.test.ts checks that every registered provider can be told apart. When two providers of one capability both look present, the capability is reported as ambiguous instead.

A pattern built on another capability sets inheritsProvider (enable-ecommerce: "payments"). It takes the detected provider instead of asking for one: resolveProvider accepts a --provider that repeats it and rejects one that differs.

requires is a Requires: the Features flags plus an optional providers map naming the providers a pattern supports per capability ({ payments: ["stripe"] }). A provider can carry its own requires, merged over the pattern's. unmetRequirements(pattern, { features, detected, provider }) lists what a project is missing. Only true flags count, and false means "not required". ui is checked separately.

blockedBy is the other direction: the features that must be off before a pattern runs, because their code imports what it removes (disable-payments is blocked by ecommerce, whose cart imports the payments client). blockingFeatures(pattern, features) lists the ones a project has on; the CLI and the harness refuse while it is not empty. ecommerce itself is a feature flag detected from src/lib/cart.svelte.ts.

A sibling root beside providers/ holds a variant of one provider's files for a project state the base files can't assume: providers-app-mode/<id>/ when auth is on, providers-cms/<id>/ when the CMS is, providers-i18n/<id>/ when wuchale is (a server load then takes the page's language from the URL, as enable-cms's layout load does). generate.ts adds the sibling's files over the base ones; allProviderPaths and the SHIPPED directory test already cover providers-*, and the new root goes in the tsconfig.json / vite.config.ts excludes.

The generated code never sees any of this. Each provider's files are what a developer would write for that provider alone, with no adapter layer or shared types for swapping providers.

Plain forms

generate-form, generate-form-remote and generate-scaffold take input.ui: "shadcn" | "plain" (default: the detected features.ui, then shadcn). plain is for projects Vela did not create: native elements with no components and no classes, data-field / data-invalid / data-error hooks for styling, components: [], and hand-written aria-invalid / aria-describedby in place of what formsnap wires up. Two more keys say what else the project lacks: flash: false reports through superforms' message() instead of sveltekit-flash-message, and serverTests: false skips server.test.ts. The CLI detects features.ui and the two keys; --ui sets input.ui, which wins over the feature. A plain scaffold lists records in a native <table> (no TanStack Table, no sorting or paging), shows one as a <dl> and edits it with the plain form markup; values render through src/core/field/plain-display.ts.

Default routes follow options.routeGroups ({ public, app }, each a group directory name or null). The CLI detects it, so a project without (public) gets src/routes/<model>; absent means the Vela layout. Only routes resolved by parseRoute (form and scaffold generators and destroyers) follow it, plus the demo pages of enable-ai and enable-content-negotiation, which move themselves; the other enable-* patterns still write into (public) / (app).

Field markup that does not go through formsnap lives in src/core/field/plain.ts, split into a binding (superforms stores, or a remote form's .as() / .issues()) and a style (shadcn Input plus tailwind classes, or native). remote.ts is the remote binding in the shadcn style, so a new field type is added once there and once in the formsnap renderer (index.ts). The integration suite checks the plain path against the bare baseline (sv create), not a Vela template.

Plain projects

Two more inputs follow the flash / serverTests convention, detected by the CLI and defaulting to what a Vela template has:

• metaTags (enable-content-negotiation): when false, the demo page's +page.ts, which imports svelte-meta-tags, is left out. Default true; the CLI sets it from package.json.
• server (enable-cms): the app runs as a Node server, so the SQLite backend can be hosted in it. Defaults to features.backend; the CLI sets it when it finds @sveltejs/adapter-node in a project without PocketBase. The self-hosted install also brings @velastack/kit, which only a backend template already has.

A pattern whose pages exist only as shadcn-svelte markup sets requires.ui: "shadcn": enable-api-keys, enable-auth, enable-auth-remote, enable-blog, enable-ecommerce, enable-notifications, enable-payments, enable-subscriptions, enable-teams and generate-scaffold-remote. Patterns with a plain variant (the form generators, generate-scaffold, enable-i18n, enable-ai) leave it unset and follow features.ui. The CLI refuses a requires.ui: "shadcn" pattern in a plain project before calling generate, so nothing is half-applied. As a backstop, installComponents() throws MissingShadcnError (exported) when the project has no components.json, before it writes anything.

enable-backend brings the server test harness to a project without one: test/setup.ts and, when the project configures vitest nowhere, the vitest.config.ts that loads it, both reported as creates.

UI components

src/ui/components/<name> holds the components Vela ships itself (data-table, multiselect, geopoint, auth-menu, ...). They are bundled as raw strings the same way creates are and copied into a project's src/lib/components/ui by installComponents() in src/runtime/write-result.ts. Everything else a pattern lists in components is handed to shadcn-svelte add, which resolves it from the style-scoped registry (/registry/styles/<style>/) named by the project's components.json.

• customDependencies must list every #lib/components/ui/<x>/index.js a shipped component imports, and customNpmPackages every npm package no shadcn item installs for it.
• data-table is a local copy of @tanstack/svelte-table's v9 adapter (createTable, FlexRender, renderComponent) over @tanstack/table-core alone; column-header, faceted-filter and data-table-pagination type their props with table-core's per-feature interfaces (Column_RowSorting<any, any>, ...), since a Column<typeof features, Row> is not assignable to Column<any, any> in v9. The scaffold list page (src/core/scaffold-list.ts) declares its own tableFeatures. installPackages never upgrades a package that is already present, so a project still on v8 is refused by assertTableCoreV9 (scaffold generators, before the collection is created) and assertTableCorePackage (installComponents()), with the upgrade steps.
• installComponents() is also exported from the package; vela ui add calls it. It is node-only and is loaded on the first call, the same rule as generate.runtime.ts. Before spawning shadcn-svelte add it checks bare item names against the style's registry index (src/runtime/registry.ts) and rejects unknown ones with an InvalidArgumentError; when the registry cannot be read the check is skipped.
• listComponents(), switchStyle(), applyBaseColor() and applyTheme() (src/runtime/ui.ts) back vela ui list, vela ui style, vela ui base and vela ui theme. Palette and font changes go through shadcn-svelte apply --preset <code> --only theme|font; the preset code is produced by the project's own shadcn-svelte/preset (src/runtime/shadcn-preset.ts), so the value lists never drift from what apply accepts. The one vendored table is STYLE_FONTS (each style's designed font), guarded by a test against the shadcn-svelte devDependency.
• WriteResultRuntime.fetch is the test seam for the registry, next to executeCommand for the spawns.

Dependency versions

src/core/versions.json is the one list of dependency ranges every vela project starts from. Three things read it:

• the patterns here install from it: spec("zod") is zod@^4.6.7, and a test refuses a name@range written inline;
• the vela CLI's minimal and static templates list the same ranges, with a test that fails when they stop (npm run sync-versions there rewrites them from this package);
• the velastack-templates baselines are built on those templates and follow them.

So a version is changed here and nowhere else. The file has four parts:

• packages: the ranges.
• node: the oldest Node a project may run on. Projects set engine-strict, so a release whose own engines.node starts above it would fail the install there.
• holds: packages kept below their latest release on purpose, each with the reason and the date. Write a block down here instead of leaving it to be rediscovered.
• tracks: packages whose range follows another project's. svelte follows the floor sv create's minimal template ships.

npm run bump-versions raises each floor to the newest release its range admits that is stable, at least three days old (--cooldown N) and installable on node; -- --check only reports. It never leaves a range: a new major or a new 0.x minor is listed as "outside the range" for someone to read the changelog, change versions.json by hand and run the integration suites against it.

The weekly Bump versions workflow runs the script, opens one pull request with what it raised, and keeps the "Dependencies outside their range" issue. The ranges reach users after a release of this package and the vela repository's Sync versions pull request; vela's daily Canary scaffolds, installs, builds and tests a new project, which is what catches a release upstream breaking one.

Workflow for adding new patterns

• Develop the pattern in the src/patterns directory.
• Use the demo script to generate a temporary project with the pattern to see applied changes.
• In the temporary project, run npm run test:server to run the tests.
• Run npm run lint and npm run check to make sure the code is correct.
• Add the pattern to a case table in integration/cases.ts (integration/coverage.test.ts fails until every registered pattern, variant and provider is covered) and run its case.

Integration tests

npm run test:integration scaffolds real projects with vela create, applies patterns the way the CLI does (feature flags re-detected from disk between steps by integration/features.ts, a hand-kept mirror of the CLI's detection: backend is data/ plus a PocketBase client dependency, since a self-hosted CMS also keeps its database under data/; getCollections reading the live schema) and then requires zero svelte-check errors with noUnusedLocals, zero failed / not-found file entries and prettier-clean output. integration/cases.ts holds one case per pattern plus stacks for patterns whose output depends on feature detection. CI runs the five suites in parallel; see .github/workflows/ci.yml.

npm run test:integration -- integration/enable.test.ts            # one suite
npm run test:integration -- integration/stacks.test.ts -t "teams" # one case

• VELA_BIN=/path/to/vela picks the CLI (default: vela on PATH). Every vela command, test:server included, runs through it, and the generated projects' own vela devDependency is dropped so it cannot shadow the build under test.
• INTEGRATION_KEEP=1 keeps generated projects; failed cases are always kept.
• vela test:server runs after each checked step in projects that have it; INTEGRATION_SERVER_TESTS=0 skips it for a faster local loop.
• STRIPE_SECRET_KEY + STRIPE_PUBLISHABLE_KEY enable the Stripe payments cases; they skip otherwise. The Shopify cases need no credentials, because nothing calls Shopify at apply time.
• node_modules is installed once per dependency set and hard-linked into every project from .integration-tests/.cache, except node_modules/$app, which SvelteKit's sync rewrites in place.
• Failures point at .integration-tests/<suite>/<case>/.integration/ (commands.log, steps.json, the raw svelte-check output). Expected failures live in integration/known-failures.ts, scoped per step or case, and turn into visible skips until they stop reproducing.

Against an unreleased CLI

Patterns are applied from this checkout, but vela create, vela sync and vela test:server come from the CLI, which loads its own installed copy of @velastack/patterns. To test a CLI branch with these patterns in it (sibling checkouts assumed):

npm run build && npm pack                                   # here: velastack-patterns-<version>.tgz
cd ../velastack-cli
npm install ../velastack-patterns/velastack-patterns-*.tgz  # or ../velastack-patterns
npm run build                                               # dist/bin.js
cd ../velastack-patterns
rm -rf .integration-tests/.cache                            # caches from an older harness or template
VELA_BIN="$PWD/../velastack-cli/dist/bin.js" npm run test:integration -- integration/enable.test.ts

The install rewrites the CLI's package.json and lockfile; restore them before committing there. In CI, run the CI workflow by hand with vela_ref set to a branch, tag or SHA of velastack/vela: the integration job does the same steps and exports VELA_BIN. Without vela_ref it installs the newest published vela that scaffolds SvelteKit 3 (latest, then next), and skips the suites with a warning when there is none.