@armynante/scaffold-cli

CLI tool for scaffolding new full-stack projects with React, Vike, Hono, and more.

Installation

# From npm/CodeArtifact
bun add -g @armynante/scaffold-cli

# Or use directly with bunx
bunx @armynante/scaffold-cli init my-app

Quick Start

# Create a full-stack project in current directory
scaffold init my-app

# Interactive mode (guided setup)
scaffold init -i

# Full-stack with database and deploy setup
scaffold init my-app --with-database --with-deploy

# Initialize in existing directory (merge with existing files)
scaffold init my-app --merge

Usage

# SSR only (no CSR example)
scaffold init my-app --ssr

# CSR only (client-side rendering)
scaffold init my-spa --csr

# API only (no frontend)
scaffold init my-api --no-frontend --no-storybook

# With database setup and initial model
scaffold init my-app --with-database --initial-model "User name:string email:string:unique"

# Specify output directory
scaffold init my-app -o ./projects/my-app

Features

By default, all features are included. Use --no-* flags to exclude:

| Feature | Description | Exclude Flag | |---------|-------------|--------------| | Frontend | React 19, Vike (SSR/CSR), Tailwind CSS, Headless UI | --no-frontend | | Backend | Hono API routes, health checks | --no-backend | | Storybook | Component library with a11y testing | --no-storybook |

Integrations

scaffold-cli integrates with external CLIs for database and deployment setup:

| Integration | CLI Required | Flag | What it creates | |-------------|--------------|------|-----------------| | Database | @armynante/database-cli | --with-database | database.config.ts, migrations, seeds, models | | Deploy | @armynante/deploy-cli | --with-deploy | Dockerfile, deploy.config.json, .env.deploy |

If the required CLI is not installed, scaffold will prompt to install it globally.

Options

-i, --interactive    Run interactive mode with prompts
-n, --name           Project name (alternative to positional)
-o, --output         Output directory (default: current directory)

--no-frontend        Exclude React/Vike frontend
--no-backend         Exclude API routes (keep health check only)
--no-storybook       Exclude Storybook

--ssr                SSR only (server-side rendering)
--csr                CSR only (client-side rendering)

--port               Server port (default: 3000)
--storybook-port     Storybook port (default: 6006)
--hmr-host           HMR host for dev server (default: localhost)

--with-database      Include database-cli setup
--with-deploy        Run deploy init (creates Dockerfile/deploy.config.json)
--skip-database      Skip database-cli setup
--skip-deploy        Skip deploy init
--database-envs      Database environments (default: dev,test)
--skip-docker        Skip Docker setup in database-cli
--initial-model      Generate initial model (e.g., "User name:string email:string")

--merge              Merge with existing files in non-empty directory
--overwrite          Overwrite existing files without prompting

-v, --verbose        Verbose output
-h, --help           Show help message
--version            Show version

Non-Empty Directory Support

scaffold-cli can initialize projects in non-empty directories:

• --merge: JSON configs (package.json, tsconfig.json) are deep-merged. Other files are overwritten.
• --overwrite: All files are overwritten without prompting.
• Interactive mode: Prompts you to choose merge, overwrite, or cancel.

# Merge into existing project
cd existing-project
scaffold init my-app --merge

# Overwrite existing files
scaffold init my-app --overwrite

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Run tests (via root vitest.config.ts)
bun run test

# Type check
bun run tsc --noEmit

Project Structure

scaffold-cli/
├── src/
│   ├── cli/
│   │   ├── index.ts        # CLI entry point
│   │   ├── commands/       # CLI commands
│   │   ├── output.ts       # Terminal output utilities
│   │   └── prompt.ts       # Interactive prompts
│   ├── services/
│   │   ├── FileService.ts         # File operations
│   │   ├── TemplateService.ts     # Template processing
│   │   ├── FileConflictService.ts # Merge/overwrite handling
│   │   ├── CLIDetectionService.ts # External CLI detection
│   │   ├── CLIInstallService.ts   # CLI auto-install/upgrade
│   │   └── ExternalCLIService.ts  # External CLI execution
│   ├── templates/
│   │   └── fullstack/      # Full-stack template
│   ├── types.ts            # TypeScript types
│   └── index.ts            # Module exports
├── dist/                   # Build output
├── package.json
└── tsconfig.json

Publishing

From the repository root:

bun run publish:scaffold

Or directly:

./scripts/codeartifact-publish.sh Modules/scaffold-cli

License

MIT