@totaland/create-starter-kit 1.0.0 → 2.0.0

package/README.md

@@ -1,42 +1,127 @@
-# create-starter-kit
+# @totaland/create-starter-kit
 
-Scaffolding tool for creating new starter-kit projects.
+Scaffolding tool for creating new starter-kit projects with a choice between backend and frontend templates.
+
+## Features
+
+- ✨ Interactive template selection (backend or frontend)
+- 🎯 CLI argument support for automation
+- 📦 Clean, production-ready templates
+- 🚀 Quick project initialization
 
 ## Usage
 
-### Using pnpm create (recommended)
+### Interactive Mode (Recommended)
 
 ```bash
-pnpm create starter-kit my-new-project
+pnpm create @totaland/starter-kit my-new-project
 ```
 
-### Using pnpm dlx
+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
+
+### With Template Argument
+
+Skip the prompt by specifying the template:
+
+```bash
+# Create backend project
+pnpm create @totaland/starter-kit my-backend backend
+
+# Create frontend project
+pnpm create @totaland/starter-kit my-frontend frontend
+```
+
+### Alternative Package Managers
+
+Using npm:
+```bash
+npm create @totaland/starter-kit@latest my-project
+```
+
+Using yarn:
+```bash
+yarn create @totaland/starter-kit my-project
+```
 
+Using pnpm dlx:
 ```bash
-pnpm dlx create-starter-kit my-new-project
+pnpm dlx @totaland/create-starter-kit my-project
 ```
 
-### Using npx
+## Templates
 
+### Backend Template
+
+**Tech Stack:**
+- Express.js (via ultimate-express)
+- TypeScript
+- Drizzle ORM with PostgreSQL
+- Scalar API documentation
+- Biome for linting/formatting
+- Vitest for testing
+
+**Features:**
+- 🏗️ Feature-based architecture
+- 🔄 JSON-driven orchestration engine
+- 📝 Comprehensive API documentation
+- 🧪 Testing setup with Vitest
+- 🗄️ Database migrations with Drizzle
+
+**After Creation:**
+```bash
+cd my-backend
+pnpm install
+pnpm dev
+```
+
+### Frontend Template
+
+**Tech Stack:**
+- React 19
+- Vite 7
+- TypeScript
+- Tailwind CSS v4
+- shadcn/ui (component library)
+- TanStack Query v5
+- React Router v7
+- Drizzle ORM
+- Biome for linting/formatting
+
+**Features:**
+- 🎨 Modern UI with Tailwind CSS v4
+- 🎯 shadcn/ui ready (add components via CLI)
+- 🔄 TanStack Query for data fetching
+- 🗺️ React Router for navigation
+- 📱 Responsive layout examples
+- 🌗 Dark mode support
+
+**After Creation:**
 ```bash
-npx create-starter-kit my-new-project
+cd my-frontend
+pnpm install
+pnpm dev
+
+# Add shadcn/ui components
+pnpm dlx shadcn@latest add button card dialog
 ```
 
-## What it does
+## What It Does
 
-1. Creates a new directory with your project name
-2. Copies the entire starter-kit template
-3. Updates the `package.json` name field to match your project name
-4. Provides next steps for installation and running the project
+1. ✅ Creates a new directory with your project name
+2. ✅ Copies the selected template (backend or frontend)
+3. ✅ Updates the `package.json` name field to match your project name
+4. ✅ Provides next steps for installation and running the project
 
 ## Local Development
 
 To test this locally before publishing:
 
-1. Build the template:
+1. Make sure templates are up to date:
    ```bash
-   cd /path/to/starter-kit
-   ./scripts/sync-template.sh
+   cd /path/to/starter-kit/create-starter-kit
+   # Templates are in ./templates/backend and ./templates/frontend
    ```
 
 2. Link the package globally:
@@ -48,7 +133,12 @@ To test this locally before publishing:
 3. Test it:
    ```bash
    cd /tmp
-   pnpm create starter-kit test-project
+   pnpm create @totaland/starter-kit test-project
+   # Select a template when prompted
+   
+   # Or specify template directly
+   pnpm create @totaland/starter-kit test-backend backend
+   pnpm create @totaland/starter-kit test-frontend frontend
    ```
 
 ## Publishing
@@ -62,5 +152,27 @@ pnpm publish
 
 Once published, anyone can use:
 ```bash
-pnpm create starter-kit my-project
+pnpm create @totaland/starter-kit my-project
 ```
+
+## Project Structure
+
+```
+create-starter-kit/
+├── bin/
+│   └── index.js          # CLI entry point
+├── templates/
+│   ├── backend/          # Backend template files
+│   └── frontend/         # Frontend template files
+├── package.json
+└── README.md
+```
+
+## Requirements
+
+- Node.js 18+
+- pnpm (recommended) or npm/yarn
+
+## License
+
+MIT

package/bin/index.js

@@ -1,26 +1,53 @@
 #!/usr/bin/env node
 
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import {
+    copyFileSync,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+    readdirSync,
+    existsSync,
+} from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import * as readline from 'node:readline/promises';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Get the project name from command line arguments
 const projectName = process.argv[2];
+const templateArg = process.argv[3]; // Optional template argument
 
 if (!projectName) {
     console.error('Error: Please provide a project name');
-    console.log('Usage: pnpm create starter-kit <project-name>');
+    console.log('Usage: pnpm create @totaland/starter-kit <project-name> [template]');
+    console.log('Templates: backend, frontend');
     process.exit(1);
 }
 
 // Resolve paths
-const templateDir = resolve(__dirname, '../template');
+const templatesDir = resolve(__dirname, '../templates');
 const targetDir = resolve(process.cwd(), projectName);
 
-console.log(`Creating new starter-kit project: ${projectName}`);
-console.log(`Target directory: ${targetDir}`);
+// Check if target directory already exists
+if (existsSync(targetDir)) {
+    console.error(`Error: Directory "${projectName}" already exists`);
+    process.exit(1);
+}
+
+// Available templates
+const TEMPLATES = {
+    backend: {
+        name: 'Backend',
+        description: 'Express.js backend with TypeScript, Drizzle ORM, and Scalar API docs',
+        dir: 'backend',
+    },
+    frontend: {
+        name: 'Frontend',
+        description: 'React + Vite with TypeScript, Tailwind CSS v4, shadcn/ui, and TanStack Query',
+        dir: 'frontend',
+    },
+};
 
 // Function to recursively copy directory
 function copyDir(src, dest) {
@@ -40,25 +67,86 @@ function copyDir(src, dest) {
     }
 }
 
-try {
-    // Copy template to target directory
-    copyDir(templateDir, targetDir);
+// Function to prompt for template selection
+async function promptTemplate() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
 
-    // Update package.json with the new project name
-    const packageJsonPath = join(targetDir, 'package.json');
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    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');
 
-    packageJson.name = projectName;
+    const answer = await rl.question('Enter your choice (1 or 2): ');
+    rl.close();
 
-    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-
-    console.log('\n✅ Project created successfully!');
-    console.log('\nNext steps:');
-    console.log(`  cd ${projectName}`);
-    console.log('  pnpm install');
-    console.log('  pnpm dev');
+    if (answer === '1' || answer.toLowerCase() === 'backend') {
+        return 'backend';
+    }
+    if (answer === '2' || answer.toLowerCase() === 'frontend') {
+        return 'frontend';
+    }
 
-} catch (error) {
-    console.error('Error creating project:', error.message);
+    console.error('Invalid choice. Please run the command again.');
     process.exit(1);
 }
+
+async function main() {
+    try {
+        // Determine which template to use
+        let templateKey;
+
+        if (templateArg) {
+            // Template specified via CLI argument
+            templateKey = templateArg.toLowerCase();
+            if (!TEMPLATES[templateKey]) {
+                console.error(`Error: Invalid template "${templateArg}"`);
+                console.log('Available templates: backend, frontend');
+                process.exit(1);
+            }
+        } else {
+            // Prompt for template selection
+            templateKey = await promptTemplate();
+        }
+
+        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');
+        }
+
+        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 === 'frontend') {
+            console.log('💡 Tip: Add shadcn/ui components with:');
+            console.log('   pnpm dlx shadcn@latest add button card dialog\n');
+        }
+    } catch (error) {
+        console.error('Error creating project:', error.message);
+        process.exit(1);
+    }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totaland/create-starter-kit",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Scaffolding tool for creating new starter-kit projects",
   "type": "module",
   "publishConfig": {
@@ -11,7 +11,7 @@
   },
   "files": [
     "bin",
-    "template"
+    "templates"
   ],
   "keywords": [
     "starter-kit",

package/templates/frontend/.env.example

@@ -0,0 +1,7 @@
+# Environment variables for the frontend application
+
+# API Base URL
+VITE_API_URL=http://localhost:3000/api
+
+# Add other environment variables as needed
+# VITE_FEATURE_FLAG=true

package/templates/frontend/README.md

@@ -0,0 +1,132 @@
+# Frontend Starter Kit
+
+A modern React + TypeScript frontend starter with carefully selected tools and libraries.
+
+## Tech Stack
+
+- **React 19** - Latest React with improved performance
+- **TypeScript** - Type-safe development
+- **Vite** - Fast build tool and dev server
+- **Tailwind CSS** - Utility-first CSS framework
+- **shadcn/ui** - Beautiful, accessible components
+- **TanStack Query** - Powerful data fetching and caching
+- **React Router** - Client-side routing
+- **Drizzle ORM** - Type-safe database access
+- **Biome** - Fast linter and formatter
+
+## Getting Started
+
+### Install Dependencies
+
+```bash
+pnpm install
+```
+
+### Development
+
+```bash
+pnpm dev
+```
+
+### Build
+
+```bash
+pnpm build
+```
+
+### Preview Production Build
+
+```bash
+pnpm preview
+```
+
+## Adding shadcn/ui Components
+
+To add shadcn/ui components, use the official CLI. For example:
+
+```bash
+# Add a button component
+pnpm dlx shadcn@latest add button
+
+# Add multiple components
+pnpm dlx shadcn@latest add button card dialog
+
+# Add all components (not recommended)
+pnpm dlx shadcn@latest add
+```
+
+Components will be added to `src/components/ui/` and can be customized as needed.
+
+## Folder Structure
+
+```
+src/
+├── components/          # Reusable components
+│   ├── layout/         # Layout components (Header, Footer, etc.)
+│   └── ui/             # shadcn/ui components (added via CLI)
+├── hooks/              # Custom React hooks
+├── lib/                # Utility functions and configurations
+│   ├── api-client.ts   # API client for HTTP requests
+│   └── utils.ts        # Common utilities (cn helper, etc.)
+├── pages/              # Page components (route-based)
+│   ├── home/
+│   └── about/
+├── App.tsx             # Main app component with routes
+├── main.tsx            # App entry point
+└── index.css           # Global styles with Tailwind
+```
+
+## Scripts
+
+- `pnpm dev` - Start development server
+- `pnpm build` - Build for production
+- `pnpm preview` - Preview production build
+- `pnpm lint` - Run Biome linter
+- `pnpm lint:fix` - Fix linting issues
+- `pnpm format` - Format code with Biome
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and update the values:
+
+```bash
+cp .env.example .env
+```
+
+## Path Aliases
+
+The project uses `@` as an alias for the `src/` directory:
+
+```typescript
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+```
+
+## Drizzle ORM Setup
+
+To use Drizzle ORM with your frontend:
+
+1. Define your schema in a shared location (e.g., `../backend/src/db/schema.ts`)
+2. Generate types: `pnpm drizzle-kit generate`
+3. Use the typed client in your queries
+
+## TanStack Query
+
+Example usage:
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+
+function MyComponent() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['myData'],
+    queryFn: () => fetch('/api/data').then(r => r.json()),
+  });
+  
+  // ...
+}
+```
+
+## License
+
+MIT