@totaland/create-starter-kit 2.0.0 → 2.0.2

package/README.md

@@ -1,10 +1,10 @@
 # @totaland/create-starter-kit
 
-Scaffolding tool for creating new starter-kit projects with a choice between backend and frontend templates.
+Scaffolding tool for creating new starter-kit projects with a choice between backend, frontend, or fullstack templates.
 
 ## Features
 
-- ✨ Interactive template selection (backend or frontend)
+- ✨ Interactive template selection (backend, frontend, or fullstack)
 - 🎯 CLI argument support for automation
 - 📦 Clean, production-ready templates
 - 🚀 Quick project initialization
@@ -20,6 +20,7 @@ pnpm create @totaland/starter-kit my-new-project
 You'll be prompted to select a template:
 - **Backend** - Express.js + TypeScript + Drizzle ORM + Scalar API docs
 - **Frontend** - React + Vite + TypeScript + Tailwind CSS v4 + shadcn/ui + TanStack Query
+- **Fullstack** - Both Backend and Frontend in one project
 
 ### With Template Argument
 
@@ -31,6 +32,9 @@ pnpm create @totaland/starter-kit my-backend backend
 
 # Create frontend project
 pnpm create @totaland/starter-kit my-frontend frontend
+
+# Create fullstack project (both backend and frontend)
+pnpm create @totaland/starter-kit my-app fullstack
 ```
 
 ### Alternative Package Managers
@@ -107,10 +111,29 @@ pnpm dev
 pnpm dlx shadcn@latest add button card dialog
 ```
 
+### Fullstack Template
+
+Creates both backend and frontend in separate subdirectories.
+
+**After Creation:**
+```bash
+cd my-app
+
+# Run backend
+cd backend
+pnpm install
+pnpm dev
+
+# Run frontend (in another terminal)
+cd frontend
+pnpm install
+pnpm dev
+```
+
 ## What It Does
 
 1. ✅ Creates a new directory with your project name
-2. ✅ Copies the selected template (backend or frontend)
+2. ✅ Copies the selected template (backend, frontend, or both for fullstack)
 3. ✅ Updates the `package.json` name field to match your project name
 4. ✅ Provides next steps for installation and running the project
 
@@ -139,6 +162,7 @@ To test this locally before publishing:
    # Or specify template directly
    pnpm create @totaland/starter-kit test-backend backend
    pnpm create @totaland/starter-kit test-frontend frontend
+   pnpm create @totaland/starter-kit test-fullstack fullstack
    ```
 
 ## Publishing

package/bin/index.js

@@ -21,12 +21,12 @@ const templateArg = process.argv[3]; // Optional template argument
 if (!projectName) {
     console.error('Error: Please provide a project name');
     console.log('Usage: pnpm create @totaland/starter-kit <project-name> [template]');
-    console.log('Templates: backend, frontend');
+    console.log('Templates: backend, frontend, fullstack');
     process.exit(1);
 }
 
-// Resolve paths
-const templatesDir = resolve(__dirname, '../templates');
+// Resolve paths - use sibling directories from the starter-kit root
+const monorepoRoot = resolve(__dirname, '../..');
 const targetDir = resolve(process.cwd(), projectName);
 
 // Check if target directory already exists
@@ -35,20 +35,45 @@ if (existsSync(targetDir)) {
     process.exit(1);
 }
 
-// Available templates
+// Available templates - reference sibling directories in the monorepo
 const TEMPLATES = {
     backend: {
         name: 'Backend',
         description: 'Express.js backend with TypeScript, Drizzle ORM, and Scalar API docs',
-        dir: 'backend',
+        sourceDir: join(monorepoRoot, 'backend'),
     },
     frontend: {
         name: 'Frontend',
         description: 'React + Vite with TypeScript, Tailwind CSS v4, shadcn/ui, and TanStack Query',
-        dir: 'frontend',
+        sourceDir: join(monorepoRoot, 'frontend'),
+    },
+    fullstack: {
+        name: 'Fullstack',
+        description: 'Both Backend and Frontend templates combined',
+        sourceDirs: [
+            { name: 'backend', path: join(monorepoRoot, 'backend') },
+            { name: 'frontend', path: join(monorepoRoot, 'frontend') },
+        ],
     },
 };
 
+// Directories and files to exclude when copying
+const EXCLUDE = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.turbo',
+    '.next',
+    '.nuxt',
+    '.output',
+    '.cache',
+    'coverage',
+    '.env',
+    '.env.local',
+    '.DS_Store',
+]);
+
 // Function to recursively copy directory
 function copyDir(src, dest) {
     mkdirSync(dest, { recursive: true });
@@ -56,6 +81,11 @@ function copyDir(src, dest) {
     const entries = readdirSync(src, { withFileTypes: true });
 
     for (const entry of entries) {
+        // Skip excluded files and directories
+        if (EXCLUDE.has(entry.name)) {
+            continue;
+        }
+
         const srcPath = join(src, entry.name);
         const destPath = join(dest, entry.name);
 
@@ -75,10 +105,11 @@ async function promptTemplate() {
     });
 
     console.log('\n📦 Select a template:\n');
-    console.log('1. Backend  - Express.js + TypeScript + Drizzle ORM');
-    console.log('2. Frontend - React + Vite + Tailwind CSS v4 + shadcn/ui\n');
+    console.log('1. Backend   - Express.js + TypeScript + Drizzle ORM');
+    console.log('2. Frontend  - React + Vite + Tailwind CSS v4 + shadcn/ui');
+    console.log('3. Fullstack - Both Backend and Frontend\n');
 
-    const answer = await rl.question('Enter your choice (1 or 2): ');
+    const answer = await rl.question('Enter your choice (1, 2, or 3): ');
     rl.close();
 
     if (answer === '1' || answer.toLowerCase() === 'backend') {
@@ -87,6 +118,9 @@ async function promptTemplate() {
     if (answer === '2' || answer.toLowerCase() === 'frontend') {
         return 'frontend';
     }
+    if (answer === '3' || answer.toLowerCase() === 'fullstack') {
+        return 'fullstack';
+    }
 
     console.error('Invalid choice. Please run the command again.');
     process.exit(1);
@@ -102,7 +136,7 @@ async function main() {
             templateKey = templateArg.toLowerCase();
             if (!TEMPLATES[templateKey]) {
                 console.error(`Error: Invalid template "${templateArg}"`);
-                console.log('Available templates: backend, frontend');
+                console.log('Available templates: backend, frontend, fullstack');
                 process.exit(1);
             }
         } else {
@@ -111,37 +145,61 @@ async function main() {
         }
 
         const template = TEMPLATES[templateKey];
-        const templateDir = join(templatesDir, template.dir);
-
-        // Verify template directory exists
-        if (!existsSync(templateDir)) {
-            console.error(`Error: Template directory not found: ${templateDir}`);
-            process.exit(1);
-        }
 
         console.log(`\n🚀 Creating ${template.name} project: ${projectName}`);
         console.log(`📁 ${template.description}\n`);
 
-        // Copy template to target directory
-        copyDir(templateDir, targetDir);
-
-        // Update package.json with the new project name
-        const packageJsonPath = join(targetDir, 'package.json');
-        if (existsSync(packageJsonPath)) {
-            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-            packageJson.name = projectName;
-            writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+        // Handle fullstack (multiple templates) or single template
+        if (template.sourceDirs) {
+            // Fullstack: copy each template to a subdirectory
+            for (const { name, path: sourceDir } of template.sourceDirs) {
+                if (!existsSync(sourceDir)) {
+                    console.error(`Error: Source directory not found: ${sourceDir}`);
+                    process.exit(1);
+                }
+                const subTargetDir = join(targetDir, name);
+                copyDir(sourceDir, subTargetDir);
+
+                // Update package.json name for each sub-project
+                const packageJsonPath = join(subTargetDir, 'package.json');
+                if (existsSync(packageJsonPath)) {
+                    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+                    packageJson.name = `${projectName}-${name}`;
+                    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+                }
+            }
+        } else {
+            // Single template
+            if (!existsSync(template.sourceDir)) {
+                console.error(`Error: Source directory not found: ${template.sourceDir}`);
+                process.exit(1);
+            }
+            copyDir(template.sourceDir, targetDir);
+
+            // Update package.json with the new project name
+            const packageJsonPath = join(targetDir, 'package.json');
+            if (existsSync(packageJsonPath)) {
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+                packageJson.name = projectName;
+                writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+            }
         }
 
         console.log('✅ Project created successfully!\n');
         console.log('📝 Next steps:');
         console.log(`   cd ${projectName}`);
-        console.log('   pnpm install');
-        console.log('   pnpm dev\n');
+        if (templateKey === 'fullstack') {
+            console.log('   cd backend && pnpm install && pnpm dev');
+            console.log('   cd frontend && pnpm install && pnpm dev\n');
+        } else {
+            console.log('   pnpm install');
+            console.log('   pnpm dev\n');
+        }
 
-        if (templateKey === 'frontend') {
+        if (templateKey === 'frontend' || templateKey === 'fullstack') {
             console.log('💡 Tip: Add shadcn/ui components with:');
-            console.log('   pnpm dlx shadcn@latest add button card dialog\n');
+            const cdPath = templateKey === 'fullstack' ? 'cd frontend && ' : '';
+            console.log(`   ${cdPath}pnpm dlx shadcn@latest add button card dialog\n`);
         }
     } catch (error) {
         console.error('Error creating project:', error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totaland/create-starter-kit",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Scaffolding tool for creating new starter-kit projects",
   "type": "module",
   "publishConfig": {

package/templates/backend/AGENTS.md

@@ -1,23 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-TypeScript sources live in `src/`, with graph traversal logic under `src/graph/` (crawl policy, state hashing, trajectory storage) and telemetry helpers in `src/telemetry.ts`. Example entrypoints such as `src/demo.ts` show how agents orchestrate flows. Generated JavaScript lands in `build/` (never hand-edit). Documentation and design notes are under `docs/`, and replay artifacts persist to `storage/` while running crawls or demo scripts. Keep tests adjacent to the code (for example `src/graph/xstate.test.ts`).
-
-## Build, Test, and Development Commands
-- `pnpm install`: sets up dependencies for both the CLI and Playwright runtime.
-- `pnpm typecheck`: runs `tsc --noEmit` against `tsconfig.json` to catch type regressions early.
-- `pnpm build`: compiles `src/` to ESM output in `build/` via SWC; use `pnpm build:debug` when you need source maps.
-- `pnpm test`, `pnpm test:watch`, `pnpm test:ui`: execute the Vitest suite in batch, watch, or UI mode.
-- `pnpm knip`: detects unused files, exports, and dependencies—fix warnings before raising a PR.
-
-## Coding Style & Naming Conventions
-Follow the repository's Biome configuration (`biome.json`) and run `npx biome check .` if needed. Use 2-space indentation, TypeScript `strict` semantics, and ECMAScript modules (`import/export`). Exported symbols and files should read as actions or nouns (`discoverState`, `persist.ts`). Tests mirror the file under test (`xstate.test.ts`). Prefer descriptive async function names reflecting their side effects.
-
-## Testing Guidelines
-Vitest drives all unit and integration coverage. Name suites after the module (`describe("bfs")`) and isolate Playwright-heavy tests behind capability checks to keep CI fast. New behavior must include at least one test validating failure handling and a corresponding happy path. Run `pnpm test` locally before committing; `storage/` fixtures may be stubbed with lightweight mocks to avoid hitting real browsers.
-
-## Commit & Pull Request Guidelines
-Use imperative, conventional messages observed in history (`feat:`, `chore:`, `fix:`). One logical change per commit, referencing an issue ID when relevant. Pull requests should describe motivation, summarize testing (`pnpm test` output, screenshots for Playwright interactions), and link design docs in `docs/` if expanded. Request review from an owner when touching crawl policy or telemetry layers, and ensure CI (typecheck, build, tests) passes before assignment.
-
-## Environment & Configuration Tips
-Configure credentials through `.env` files consumed by Crawlee/Playwright—never hard-code tokens. For telemetry, set OpenTelemetry exporters via environment variables before running demos. Heavy crawls persist checkpoints to `storage/`; clean stale runs before committing to keep diffs focused.

package/templates/backend/ARCHITECTURE.md

@@ -1,53 +0,0 @@
-# Architecture Pattern Examples
-
-This starter kit demonstrates a blend of patterns from **"Designing Data-Intensive Applications"** and **"Patterns of Enterprise Application Architecture"**.
-
-## Order System Example
-
-### From Designing Data-Intensive Applications (DDIA):
-
-1. **Event Sourcing** - All state changes stored as immutable events
-   - `order.entity.ts`: Events are the source of truth
-   - Events: `OrderCreated`, `ItemAdded`, `OrderPlaced`
-
-2. **CQRS (Command Query Responsibility Segregation)**
-   - Commands: `commands.usecase.ts` - Write operations that generate events
-   - Queries: `queries.usecase.ts` - Read operations from materialized views
-
-3. **Materialized Views** - Denormalized data for fast queries
-   - `order.repository.impl.ts`: `readModel` maintains pre-computed summaries
-   - User index for O(1) lookups by user ID
-
-4. **Append-Only Log** - Event store never modifies existing data
-   - New events are appended, never updated or deleted
-
-### From Patterns of Enterprise Application Architecture (PEAA):
-
-1. **Repository Pattern** - Abstract data access
-   - `order.repository.ts`: Interface defining data operations
-   - Separates domain logic from persistence
-
-2. **Domain Model** - Rich business logic in entities
-   - `order.entity.ts`: Order entity with business rules and validation
-
-3. **Use Case / Service Layer** - Application logic orchestration
-   - Commands and queries as separate use cases
-   - Transaction boundaries and workflow management
-
-## API Endpoints
-
-```
-POST   /orders              # Create new order
-POST   /orders/:id/items    # Add item to order
-POST   /orders/:id/place    # Place order
-GET    /orders/:id          # Get order details
-GET    /orders/user/:userId # Get user's orders (fast via materialized view)
-GET    /orders/:id/events   # Get event stream (audit log)
-```
-
-## Key Benefits
-
-- **Scalability**: Read/write separation allows independent scaling
-- **Auditability**: Complete event history for compliance/debugging
-- **Performance**: Materialized views optimize common queries
-- **Maintainability**: Clean architecture with separated concerns

package/templates/backend/ORDER_SYSTEM.md

@@ -1,93 +0,0 @@
-# Order System with Drizzle ORM
-
-## Setup
-
-### 1. Environment Variables
-
-Create a `.env` file:
-
-```bash
-# Optional: PostgreSQL connection (if not set, uses in-memory)
-DATABASE_URL=postgres://user:password@localhost:5432/orders_db
-
-PORT=3000
-```
-
-### 2. Database Setup (Optional - for PostgreSQL)
-
-If you want to use PostgreSQL instead of in-memory storage:
-
-```bash
-# Generate migration
-pnpm drizzle-kit generate
-
-# Run migration
-pnpm drizzle-kit migrate
-
-# Or use push for development
-pnpm drizzle-kit push
-```
-
-### 3. Run the Server
-
-```bash
-# Development
-pnpm dev
-
-# Production
-pnpm build
-pnpm start
-```
-
-## API Endpoints
-
-Base URL: `http://localhost:3000/api`
-
-### Create Order
-```bash
-POST /api/orders
-Content-Type: application/json
-
-{
-  "userId": "550e8400-e29b-41d4-a716-446655440000"
-}
-```
-
-### Add Item to Order
-```bash
-POST /api/orders/:orderId/items
-Content-Type: application/json
-
-{
-  "productId": "660e8400-e29b-41d4-a716-446655440000",
-  "quantity": 2,
-  "price": 29.99
-}
-```
-
-### Place Order
-```bash
-POST /api/orders/:orderId/place
-```
-
-### Get Order Details
-```bash
-GET /api/orders/:orderId
-```
-
-### Get User's Orders (Fast - from materialized view)
-```bash
-GET /api/orders/user/:userId
-```
-
-### Get Order Event Stream (Audit log)
-```bash
-GET /api/orders/:orderId/events
-```
-
-## Architecture
-
-- **No DATABASE_URL**: Uses in-memory repository (for testing/demo)
-- **With DATABASE_URL**: Uses Drizzle ORM with PostgreSQL
-- Event Sourcing with materialized views for optimal read performance
-- CQRS pattern with separate command and query operations

package/templates/backend/biome.json

@@ -1,3 +0,0 @@
-{
-  "extends": ["../biome.json"]
-}

package/templates/backend/drizzle.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from 'drizzle-kit';
-
-export default defineConfig({
-  schema: './src/infrastructure/database/schema.ts',
-  out: './drizzle',
-  dialect: 'postgresql',
-  dbCredentials: {
-    url: process.env.DATABASE_URL || 'postgres://localhost:5432/orders_db',
-  },
-});

package/templates/backend/knip.json

@@ -1,10 +0,0 @@
-{
-  "$schema": "https://unpkg.com/knip@5/schema.json",
-  "ignoreExportsUsedInFile": {
-    "interface": true,
-    "type": true
-  },
-  "tags": [
-    "-lintignore"
-  ]
-}

package/templates/backend/package.json

@@ -1,55 +0,0 @@
-{
-  "name": "ultimate-express-starter",
-  "version": "1.0.0",
-  "description": "Fast TypeScript backend starter kit with Ultimate Express, Scalar API docs, and Drizzle ORM.",
-  "type": "module",
-  "main": "build/index.js",
-  "scripts": {
-    "start": "node build/index.js",
-    "dev": "swc src -d build --strip-leading-paths --copy-files --watch & node --watch build/index.js",
-    "typecheck": "npx tsc --noEmit",
-    "build": "swc src -d build --strip-leading-paths --copy-files",
-    "build:debug": "swc src -d build --strip-leading-paths --copy-files --source-maps",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "prebuild": "rm -rf build",
-    "knip": "knip",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio"
-  },
-  "files": [
-    "build"
-  ],
-  "devDependencies": {
-    "@biomejs/biome": "2.0.6",
-    "@swc-node/register": "^1.11.1",
-    "@swc/cli": "0.7.7",
-    "@swc/core": "^1.10.1",
-    "@types/bun": "1.2.14",
-    "@types/cors": "^2.8.19",
-    "@types/node": "24.0.7",
-    "@vitest/ui": "^3.2.4",
-    "knip": "^5.69.1",
-    "tsx": "^4.20.6",
-    "typescript": "^5.8.3",
-    "vitest": "^4.0.10"
-  },
-  "dependencies": {
-    "@scalar/express-api-reference": "^0.8.25",
-    "cors": "^2.8.5",
-    "dotenv": "17.0.0",
-    "drizzle-kit": "^0.31.7",
-    "drizzle-orm": "^0.44.7",
-    "lru-cache": "^11.2.2",
-    "postgres": "^3.4.7",
-    "ultimate-express": "^2.0.12",
-    "ultimate-ws": "^2.0.6",
-    "zod": "^4.1.12"
-  },
-  "trustedDependencies": [
-    "@swc/core"
-  ]
-}

package/templates/backend/playwright.config.ts

@@ -1,16 +0,0 @@
-import { defineConfig } from "@playwright/test";
-import { config as loadEnv } from "dotenv";
-
-// Load environment variables (e.g. PLAYWRIGHT_BASE_URL) before tests spin up.
-loadEnv();
-
-export default defineConfig({
-  testDir: "src/generated/tests",
-  reporter: [
-    ["line"],
-    ["html", { outputFolder: "playwright-report", open: "never" }],
-  ],
-  use: {
-    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:3000",
-  },
-});

package/templates/backend/pnpm-workspace.yaml

@@ -1,3 +0,0 @@
-onlyBuiltDependencies:
-  - '@swc/core'
-  - esbuild

package/templates/backend/src/features/health/controller.ts

@@ -1,5 +0,0 @@
-import type { Request, Response } from 'ultimate-express';
-
-export const getHealth = (req: Request, res: Response) => {
-    res.json({ status: 'ok', timestamp: new Date().toISOString() });
-};

package/templates/backend/src/features/health/index.ts

@@ -1,6 +0,0 @@
-import { Router } from 'ultimate-express';
-import { getHealth } from './controller.js';
-
-export const healthRouter = Router();
-
-healthRouter.get('/', getHealth);

package/templates/backend/src/features/orders/controller.ts

@@ -1,13 +0,0 @@
-import type { Request, Response } from 'ultimate-express';
-
-export const getOrders = (req: Request, res: Response) => {
-    res.json([
-        { id: 1, item: 'Laptop', price: 1200 },
-        { id: 2, item: 'Mouse', price: 25 },
-    ]);
-};
-
-export const createOrder = (req: Request, res: Response) => {
-    const { item, price } = req.body;
-    res.status(201).json({ id: 3, item, price });
-};

package/templates/backend/src/features/orders/index.ts

@@ -1,7 +0,0 @@
-import { Router } from 'ultimate-express';
-import { createOrder, getOrders } from './controller.js';
-
-export const ordersRouter = Router();
-
-ordersRouter.get('/', getOrders);
-ordersRouter.post('/', createOrder);

package/templates/backend/src/index.ts

@@ -1,76 +0,0 @@
-// example backend with ultimate-express
-import 'dotenv/config';
-import express from 'ultimate-express';
-import type { Request, Response } from 'ultimate-express';
-import cors from 'cors';
-import { ordersRouter } from './features/orders/index.js';
-import { healthRouter } from './features/health/index.js';
-import { apiReference } from '@scalar/express-api-reference';
-
-const app = express();
-
-app.use(cors());
-app.use(express.json());
-
-app.get('/', (req: Request, res: Response) => {
-  res.send('Hello, Ultimate Express!');
-});
-
-// Mount feature routes
-app.use('/api/orders', ordersRouter);
-app.use('/api/health', healthRouter);
-
-// API Documentation with Scalar
-app.use(
-  '/api/docs',
-  apiReference({
-    spec: {
-      url: '/openapi.json',
-    },
-  }),
-);
-
-// Example OpenAPI spec endpoint
-app.get('/openapi.json', (req: Request, res: Response) => {
-  res.json({
-    openapi: '3.1.0',
-    info: {
-      title: 'Ultimate Express API',
-      version: '1.0.0',
-      description: 'API documentation for Ultimate Express starter kit',
-    },
-    servers: [
-      {
-        url: `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Development server',
-      },
-    ],
-    paths: {
-      '/': {
-        get: {
-          summary: 'Hello endpoint',
-          description: 'Returns a greeting message',
-          responses: {
-            '200': {
-              description: 'Successful response',
-              content: {
-                'text/html': {
-                  schema: {
-                    type: 'string',
-                    example: 'Hello, Ultimate Express!',
-                  },
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  });
-});
-
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  console.log(`Server is running on http://localhost:${PORT}`);
-  console.log(`API Documentation available at http://localhost:${PORT}/api/docs`);
-});

package/templates/backend/tsconfig.build.json

@@ -1,10 +0,0 @@
-{
-	"extends": "./tsconfig.json",
-	"compilerOptions": {
-		"noEmit": false,
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true
-	},
-	"exclude": ["node_modules", "build", "**/*.test.ts", "**/*.spec.ts"]
-}