@quanticjs/create-app

Scaffold and maintain QuanticJS projects — NestJS modular monolith + React frontend + Docker + Claude Code AI rules.

Quick Start

npx @quanticjs/create-app my-app

Interactive prompts ask for modules, frontend preference, and optional packages. Then:

cd my-app
docker compose up           # Start PostgreSQL, Redis, Keycloak, backend
cd client && npm run dev    # Start frontend (separate terminal)
open http://localhost:5173

CLI Usage

Create a New Project

# Interactive
npx @quanticjs/create-app

# Non-interactive
npx @quanticjs/create-app my-app \
  -d "My project description" \
  -m "change-request,notification" \
  --frontend \
  --packages "workflow,events,redis"

# Backend-only (no React frontend)
npx @quanticjs/create-app my-api \
  -d "API service" \
  -m "billing" \
  --no-frontend

# Preview without writing
npx @quanticjs/create-app my-app --dry-run

Options

| Flag | Description | |------|-------------| | -d, --description <desc> | Project description | | -m, --modules <modules> | Comma-separated initial module names | | --frontend / --no-frontend | Include or skip React frontend (default: include) | | --packages <packages> | Comma-separated @quanticjs backend packages | | --no-install | Skip npm install | | --no-git | Skip git init | | --dry-run | Show what would be created without writing files |

Available Backend Packages

| Package | Description | |---------|-------------| | @quanticjs/workflow | Workflow engine integration | | @quanticjs/events-kafka | Kafka domain events + outbox pattern (installs @quanticjs/events-core too; events is accepted as an alias) | | @quanticjs/redis | Redis utilities | | @quanticjs/metrics | Prometheus metrics | | @quanticjs/feature-flags | Feature flags (Unleash) |

Sync an Existing Project

When create-app templates are updated (Docker fixes, script improvements, CLAUDE.md changes), existing projects can pull the latest changes without re-scaffolding. Sync also migrates pre-plugin projects: it removes local rules/skills/hooks copies that are now distributed by the quanticjs-standards plugins.

First-time setup (existing projects)

Projects created before the sync feature need a one-time init:

cd my-existing-project
npx @quanticjs/create-app sync --init

This creates .quanticjs.json by auto-detecting your project configuration (modules, frontend, packages). New projects get this file automatically.

Syncing

# Interactive — review each changed file
npx @quanticjs/create-app sync

# Preview changes without applying
npx @quanticjs/create-app sync --dry-run

# Apply all changes (CI-friendly, non-interactive)
npx @quanticjs/create-app sync --apply

# Sync a project in a different directory
npx @quanticjs/create-app sync /path/to/project

What gets synced

Sync regenerates infrastructure and tooling files from the latest templates and diffs them against your project:

| Category | Files | |----------|-------| | Claude Code config | CLAUDE.md, .claude/settings.json, .claude/mcp.json | | Project-specific skills | .claude/skills/add-workflow/SKILL.md | | Docker | Dockerfile, docker-compose.yml, docker-compose.test.yml | | Scripts | scripts/init-db.sh, scripts/save-auth-state.ts | | Root config | .gitignore, .prettierrc |

Sync also removes plugin-superseded files — local copies of .claude/hooks/ and the shared skills that are now distributed via the quanticjs-standards plugins (local copies shadow the plugin versions and block updates). Shared rules in .claude/rules/ are left alone: the quanticjs-hooks plugin's SessionStart hook keeps them up to date in place.

Sync does not touch your application code (src/, client/src/), package.json dependencies, migrations, or any custom files you've added.

Interactive review mode

When run without --apply, sync shows a summary and lets you choose:

Sync summary: 3 changed, 5 plugin-superseded, 12 up to date

  New files (1):
    + .claude/skills/add-workflow/SKILL.md

  Modified files (2):
    ~ docker-compose.yml
    ~ CLAUDE.md

  Superseded by quanticjs-standards plugins (5):
    - .claude/hooks
    - .claude/skills/add-feature
    - .claude/skills/add-handler
    ...

? How do you want to apply changes?
  > Review each file individually
    Apply all changes
    Apply new files only (skip modified)
    Abort

In review mode, each modified file shows a colored unified diff so you can decide per-file.

.quanticjs.json

This file stores your project's scaffold configuration. Commit it to your repo.

{
  "projectName": "delivery-hub",
  "projectDescription": "IT delivery workflow platform",
  "modules": ["change-request", "notification"],
  "includeFrontend": true,
  "backendPackages": ["@quanticjs/workflow", "@quanticjs/events"],
  "createdAt": "2026-05-25T15:07:51.363Z",
  "createAppVersion": "0.1.4"
}

What Gets Generated

my-app/
  .claude/                      # Claude Code AI configuration
    settings.json               # Permissions + quanticjs-standards marketplace + plugins
    skills/add-workflow/        # Project-specific skill (shared skills come from the plugin)
    mcp.json                    # Playwright MCP for browser testing
  src/
    main.ts                     # bootstrapService() from @quanticjs/core
    app.module.ts               # Root module — BffModule.forRoot() from @quanticjs/auth-web-bff
    data-source.ts              # TypeORM CLI config
    <module>/                   # Your domain modules
      commands/
      queries/
      entities/
      dtos/
      controllers/
      <module>.module.ts
    migrations/                 # TypeORM migration (schema creation)
  client/                       # (if --frontend)
    src/
      main.tsx
      App.tsx
      pages/
      lib/
    e2e/                        # Playwright E2E tests
    vite.config.ts
    playwright.config.ts
  Dockerfile                    # Multi-stage (dev + production)
  docker-compose.yml            # PostgreSQL, Redis, Keycloak, backend
  docker-compose.test.yml       # Isolated test stack (ports 3099, 8099)
  scripts/
    init-db.sh                  # Database + schema init
    save-auth-state.ts          # Keycloak auth state for E2E tests
  .quanticjs.json               # Sync config
  CLAUDE.md                     # Project-level Claude instructions
  package.json

Architecture

Generated projects follow the QuanticJS modular monolith pattern:

• CQRS — Commands + Queries dispatched via NestJS CommandBus/QueryBus
• Pipeline behaviors — @Validate (Zod), @Cache (Redis), @DistributedLock, @FeatureFlag
• Thin controllers — Parse HTTP, dispatch to bus, return result
• Result<T> — No exceptions for business errors
• BFF auth — Keycloak OIDC, httpOnly cookies, server-side token storage in Redis
• Schema per module — Each module owns its own PostgreSQL schema
• Outbox pattern — Domain events written atomically, published via Kafka (@quanticjs/events-kafka)

Claude Code Integration

Shared standards are not copied into generated projects — they are distributed by the quanticjs-standards plugin marketplace. Generated projects ship a .claude/settings.json that registers the marketplace and enables two plugins, so every developer who clones the repo gets them automatically:

| Plugin | Provides | |--------|----------| | quanticjs-hooks@quanticjs-standards | SessionStart hook that syncs the shared rules (CQRS, thin controllers, Result<T>, BFF auth, testing, etc.) into .claude/rules/, plus safety hooks (destructive-command guard, secret detection, auto-format, compaction recovery) | | quanticjs-scaffolding@quanticjs-standards | 31 slash-command skills: /add-feature, /add-handler, /add-entity, /add-module, /add-frontend-page, /write-backend-tests, /write-ui-tests, /e2e-*, /int-*, and more |

Edit a rule or skill once in the quanticjs-standards repo and every project picks it up on the next plugin update cycle — no per-project re-sync needed.

Only project-specific Claude assets stay in the scaffolded repo:

| Asset | Purpose | |-------|---------| | CLAUDE.md | Project stack, ports, conventions, skill routing | | .claude/skills/add-workflow/ | QuanticFlow workflow integration (tied to scaffolded module layout) | | .claude/mcp.json | Playwright MCP for browser testing |

Note: On the very first session after cloning, the SessionStart hook copies rules to disk but they load from the second session onwards. To bootstrap immediately, run the standalone sync-rules.sh from the quanticjs-standards repo.

License

MIT