create-quadrokit

Scaffold a QuadroKit Vite app from a built-in template.

Usage (this monorepo)

# from repository root
bun create-quadrokit/src/index.ts --template dashboard --dir /path/to/my-app

Flags

| Flag | Description | |------|-------------| | --template <name> | dashboard | website | ecommerce | admin-shell | | --dir <path> | Target directory relative to cwd (created; must be empty if it already exists) | | --name <name> | Same as --dir (project folder name); ignored if --dir is set | | -y / --yes | Non-interactive: requires --template; uses quadro-<template> as the directory unless --dir / --name is set; copies .env.example → .env, runs git init and install without prompting (override with --no-copy-env / --no-git / --no-install) | | -h / --help | Print usage and exit | | --keep-workspace | Keep workspace:* in package.json (for development inside the QuadroKit monorepo only) | | --git / --no-git | Initialize a git repo after scaffolding (skip the prompt) | | --install / --no-install | Run bun install or npm install after scaffolding (skip the prompt) | | --copy-env / --no-copy-env | Copy .env.example to .env after scaffolding (skip the prompt) |

The banner shows create-quadrokit’s package version (e.g. v0.2.2).

On start, the CLI prints a short prerequisites check (Node.js, Bun, Git). Node 18+ is required; Bun is optional (falls back to npm for installs). Git is only needed if you choose to init a repository.

Interactive mode: run without --template / --dir / --name to be prompted. If the project directory already exists and is not empty, you are asked again for a different name. You are then asked whether to copy .env.example → .env, then about git and install, unless -y or the explicit flags above apply.

What it does

1. Copies the chosen template from create-quadrokit/templates/<name> when installed from npm, or packages/templates/<name> when you run the CLI from the monorepo (skips node_modules, dist, .quadrokit, lockfiles).
2. Overlays template-common/ (shared across all templates): .env.example, vite.config.ts, tailwind.config.ts, tsconfig*.json, postcss.config.js, biome.json, src/vite-env.d.ts, .github/workflows/ci.yml, .gitlab-ci.yml, .cursor/rules/commitlint-conventional.mdc, .agents/skills/**, skills-lock.json, etc. In the monorepo, packages/templates/* receives the same overlay via bun run sync:template-common except .github/ and .gitlab-ci.yml (those are for generated repos; the QuadroKit monorepo uses .github/workflows/ci.yml at the repo root). Paths like vite.config.ts are gitignored under packages/templates/ so only template-common/ is the source of truth in git.
3. Rewrites src/lib/quadro-client.ts to import from @quadrokit/generated/client.gen.js (alias in vite.config.ts / tsconfig.app.json).
4. Removes @quadrokit/sample-client and rewrites any workspace:… protocol on @quadrokit/* deps to published semver ranges. quadrokitScaffoldVersions in this package’s package.json pins ^ ranges for @quadrokit/client and @quadrokit/ui (fallback: ^<create-quadrokit version>). Use --keep-workspace only for development inside the QuadroKit repo.

Publishing create-quadrokit to npm

Before publishing a new create-quadrokit version, bump @quadrokit/client and @quadrokit/ui in the monorepo as needed, then quadrokitScaffoldVersions must match those releases so bunx create-quadrokit scaffolds apps that install the right packages from the registry.

• Automated: prepublishOnly runs scripts/sync-scaffold-versions.ts, which sets quadrokitScaffoldVersions from packages/client/package.json and packages/ui/package.json version fields (as ^x.y.z). Run bun run scripts/sync-scaffold-versions.ts from create-quadrokit/ anytime to refresh the field before committing.
• Manual: If you ever edit quadrokitScaffoldVersions by hand, align ^ ranges with the published @quadrokit/client / @quadrokit/ui versions users will install.

5. Writes QUADROKIT.md with Next steps: set the right .env values (see .env.example), then run bun run quadrokit:generate to type the REST client. Does not copy .quadrokit/generated — generation is required after install.
6. Adds a root .gitignore (unless the template already shipped one).
7. Optionally copies .env.example to .env (prompt, or defaults with -y; use --no-copy-env to skip).
8. Optionally runs git init, installs dependencies (bun if available, otherwise npm), then git add -A and an initial commit with message chore: init project so bun.lock / package-lock.json are included when install ran.

Published usage (future)

After publishing to npm:

bunx create-quadrokit@latest --template dashboard

Ensure @quadrokit/client, @quadrokit/ui, etc. are published at compatible versions.