Scaffolding CLI for Next.js and TanStack Start: ViraStack tools and AI rules in one command
Features
- Interactive CLI: Interactive prompts for template selection, project naming, and ecosystem tool integration.
- Production-Ready Foundations: Scaffolds Next.js or TanStack Start projects with a pre-configured feature-based architecture.
- Built-in AI Protocols: Asks which AI coding tools you use (Claude Code, Cursor) and sets up ViraStack AI for them — architecture rules in each tool's native format,
AGENTS.md, and design skills from Emil Kowalski and Jakub Krehel — giving your coding agents a strict "constitution" from day one.
- End-to-End Type Safety: Strict TypeScript rules, Zod validation, and native package manager alignment (pnpm, npm, yarn, bun).
- Ecosystem Integration: Add optional ViraStack tools (
@virastack/mask, @virastack/password, @virastack/address) seamlessly.
- Modules: Add a working feature (
users, checkout-address, checkout-card, products, cart) to your project, and remove it again, with one command.
Quick Start
Recommended (pnpm):
pnpm dlx virastack
Alternatives:
npx virastack
# or
yarn dlx virastack
# or
bunx virastack
What it asks
What is your project named?
virastack-app
Which template would you like to use?
› Next.js App Router
TanStack Start
Which AI coding tools do you use?
[x] Claude Code
[x] Cursor
Would you like multi-language (i18n) support?
› Yes
No
Which ViraStack tools would you like to include?
[ ] @virastack/mask
[ ] @virastack/password
[ ] @virastack/address
Select none to get plain rules in .agents/rules/ that any agent can read through AGENTS.md.
What it sets up
- Copies the template and sets the project name.
- Installs dependencies with the package manager you ran it with.
- Next.js only: adds the Next.js block to
AGENTS.md, pointing agents at the docs bundled in node_modules/next/dist/docs/.
- Runs
@virastack/ai init --agent <your choice>. It never overwrites files you changed.
- Installs three design skills:
emil-design-eng (Emil Kowalski), better-ui and better-accessibility (Jakub Krehel). They go to .agents/skills/ and, with Claude Code, to .claude/skills/. With Claude Code as the only tool, they go only to .claude/skills/.
- Creates the first git commit, so
git status is clean.
--skip-install skips step 2. Offline, steps 2, 4 and 5 are skipped and the commands to run later are printed.
Tools
| Tool | Description |
|---|
@virastack/ai | Architecture rules for Claude Code, Cursor and AGENTS.md (included in templates by default) |
@virastack/mask | Input masks for React Hook Form: phone, card, date, currency |
@virastack/password | Accessible password hook: show/hide, strength, server checks |
@virastack/address | Turkish address hook: province, district, neighbourhood and postal code |
Commands and options
| Command / flag | Description |
|---|
init [name] | Create a new project (default; also runs with no command) |
add <name> | Add a tool (mask, password, address, ai) or a module to an existing project |
remove <module> | Remove a module. Its packages stay |
--name <name> | Project name (or pass as positional / .) |
--template <name> | nextjs or tanstack |
--tools <list> | Comma-separated tools (mask,password,address) |
--agent <list> | AI coding tools: claude, cursor (comma separated) or none. Default with --yes: both |
--i18n / --no-i18n | Enable or disable the i18n template |
--no-pages | With add: leave a module's pages out, for a project with its own |
--yes, -y | Non-interactive mode (flags + defaults) |
--skip-install | Skip dependency install (AI rules and skills are still added) |
--tr | Turkish prompts |
--telemetry-disable | Permanently disable anonymous usage tracking |
-v, --version | Print CLI version |
-h, --help |
pnpm dlx virastack add mask
pnpm dlx virastack add password
pnpm dlx virastack add address
pnpm dlx virastack add ai
pnpm dlx virastack add ai --agent cursor
pnpm dlx virastack add users
pnpm dlx virastack add products
pnpm dlx virastack remove users
add installs a module's feature. A module with pages of its own, such as products, brings them too and lists their URLs; it stops, writing nothing, when the project already has a route there, and --no-pages installs the feature alone. A module without pages prints the import line and a link with the steps for your framework. See the module docs.
Included by default
Every template ships with this stack already installed:
| Area | Packages |
|---|
| State | TanStack Query, Zustand, nuqs (Next.js; TanStack Start uses validateSearch) |
| Form | React Hook Form, Zod |
| Hooks | usehooks-ts |
| UI | Base UI, Lucide React |
| Test | Vitest, Testing Library, MSW |
ViraStack AI encodes these choices as agent rules so assistants follow the same stack from day one.
Telemetry
The CLI collects anonymous usage data only: template, options, tools, package manager and CLI version. Opt out: pnpm dlx virastack --telemetry-disable
Contributing
Ideas and bug reports are welcome — open an issue.
Ecosystem
Part of the ViraStack ecosystem: Academy · AI · Mask · Password · Address · Guide
License
MIT © Ömer Gülçiçek
