@ctrliq/create-quantic-app

Scaffold a new app pre-wired with the Quantic design system.

It generates a Vite + React + TanStack Router project with Quantic's components, tokens, fonts, and lint/tsconfig presets already in place, then lets you opt into extras like CI, end-to-end tests, data fetching, forms, and i18n.

Quick start

pnpm create @ctrliq/quantic-app my-app

or with npm:

npm create @ctrliq/quantic-app@latest my-app

Then:

cd my-app
pnpm install
pnpm dev

Requires Node >=24 and pnpm >=11.

Usage

There are three ways to configure the generated app.

Interactive wizard (default)

Run without options and answer the prompts:

pnpm create @ctrliq/quantic-app my-app

You'll be asked how to write styles and whether to include CI, e2e tests, data fetching, forms, and i18n. If you omit the project name, the wizard asks for it too.

Presets

Skip the questions with a named preset:

pnpm create @ctrliq/quantic-app my-app --preset full

| Preset | Styling | CI | e2e | query | forms | i18n | | --------- | ------------ | --- | --- | ----- | ----- | ---- | | minimal | SCSS modules | – | – | – | – | – | | full | SCSS modules | ✓ | ✓ | ✓ | ✓ | ✓ |

Flags

Or pick features individually (non-interactive):

pnpm create @ctrliq/quantic-app my-app --ci --query --styling css-modules

| Flag | Default | Description | | --------------------- | -------------- | -------------------------------------------------- | | --styling <choice> | scss-modules | scss-modules or css-modules | | --ci | off | GitHub Actions workflow (typecheck, lint, test) | | --e2e | off | Playwright browser tests | | --query | off | TanStack Query for backend data fetching | | --forms | off | TanStack Form + Zod for validated forms | | --i18n | off | Lingui for multi-language support |

What you get

Every generated app includes:

• Vite + React with TanStack Router
• Quantic packages — @ctrliq/quantic-react, -css, -tokens, -fonts
• SCSS or CSS modules for component styles
• Vitest for unit tests
• ESLint, Stylelint and Prettier via Quantic's shared configs (@ctrliq/quantic-eslint-config, @ctrliq/quantic-stylelint-config, @ctrliq/quantic-tsconfig)

Optional layers, when selected:

• CI — a GitHub Actions workflow that runs typecheck, lint, and tests on every pull request
• e2e — Playwright with an example spec and test:e2e / test:e2e:ui scripts
• query — TanStack Query wired up for API calls
• forms — TanStack Form + Zod
• i18n — Lingui with i18n:extract / i18n:compile scripts

How it works

The scaffolder composes the project from independent template layers under templates/:

base                          always
frameworks/tanstack-router    always
styling/{scss,css}-modules    always (your choice)
ci/github-actions             --ci
e2e/playwright                --e2e
query                         --query
forms                         --forms
i18n/lingui                   --i18n

Each layer is copied into the target directory in order. Every layer can carry a _deps.json declaring its dependencies; these are merged into a single generated package.json. During the copy, __PROJECT_NAME__ placeholders are replaced with your project name, and dotfiles shipped as _gitignore, _npmrc, and _env are renamed to .gitignore, .npmrc, and .env.

To add a new optional feature, create a templates/<feature>/ directory with its files and a _deps.json, then wire it into the layer list in src/scaffold.ts and the wizard/flags in src/wizard.ts and src/cli.ts.

Development

pnpm build       # bundle src/ to dist/ with Rollup (production output)
pnpm typecheck   # tsc --noEmit

The published package ships the compiled dist/ and the templates/ directory.

Develop from the monorepo: the layering engine comes from the unpublished @ctrliq/quantic-scaffold-core, so installing devDependencies outside the workspace 404s.

Iterating on the CLI

You don't need to build to run the scaffolder. pnpm dev runs the TypeScript source directly (via tsx, no build step), wiping and regenerating a scratch app in .dev-out/app each time so you can inspect the output:

pnpm dev           # scaffold with the `full` preset into .dev-out/app
pnpm dev:minimal   # scaffold with the `minimal` preset

To test a specific feature combination, run tsx directly with your own flags:

tsx src/cli.ts .dev-out/app --styling css-modules --query --i18n

.dev-out/ is gitignored. Use this loop when you're changing CLI logic — the wizard, flag parsing, or layer composition in src/.

Iterating on template content

To edit the actual files a generated app contains (components, styles, configs), re-running the scaffolder for every tweak is slow. Instead, scaffold once and work inside the generated app with live reload:

pnpm dev:start   # scaffold .dev-out/app, install its deps, start its Vite server

That's a shortcut for scaffolding, then cd .dev-out/app && pnpm install && pnpm dev. Edit files in the generated app to iterate with instant feedback (HMR), then copy the changes back into the matching layer under templates/. Re-run the scaffolder only when you change how layers combine rather than their contents.