Stacksmith

A modern CLI tool for scaffolding JavaScript/TypeScript projects with best practices built-in.

Stacksmith helps you bootstrap new projects with sensible defaults and modern tooling, so you can focus on building instead of configuring.

✨ Features

• 🎯 Interactive CLI - Guided prompts for project setup
• ⚡️ React + Vite - Fast development with HMR
• 📦 Smart Defaults - TypeScript, Biome, Vitest pre-configured
• 🔧 Flexible - Choose JavaScript or TypeScript
• 🎨 Feature Selection - Add only what you need
• 📝 Well Tested - 95%+ code coverage with comprehensive test suite

🚀 Quick Start

# Run directly with npm/pnpm/yarn
npx stacksmith create my-app

# Or install globally
npm install -g stacksmith
stacksmith create my-app

📖 Usage

Interactive Mode

Simply run stacksmith create and follow the prompts:

stacksmith create

You'll be asked to configure:

• Project name - Validated against npm package rules
• Template - React App (more coming soon)
• Language - TypeScript (default) or JavaScript
• Package Manager - pnpm (default), npm, or yarn
• Features - Vitest, Biome, VSCode config, and more

Non-Interactive Mode

Pass options to skip prompts:

stacksmith create my-app \
  --template react-app \
  --typescript \
  --package-manager pnpm \
  --features vitest,biome,vscode

Available Options

• --template <name> - Project template (currently: react-app)
• --typescript - Use TypeScript (default)
• --javascript - Use JavaScript instead
• --package-manager <pm> - Package manager (pnpm, npm, yarn)
• --features <list> - Comma-separated feature list
• --with <flags> - Native adapter flags (e.g., --with "--template blog --typescript strict")
• --adapter-command <cmd> - Full native create command to parse
• --adapter-flags <flags> - Comma-separated adapter-specific flags (key=value,key2=value2). Example: --adapter-flags template=blog,typescript=strict for Astro; --adapter-flags tailwind=true for Next.js.
• --config <path> - Path to config file (default: .stacksmithrc in cwd or home directory)
• --dry-run - Preview configuration and commands without executing

Adapter-Specific Flags

Some official template adapters (e.g. Next.js, Astro) support additional flags beyond Stacksmith's core options. Use --adapter-flags to pass them through directly. These are forwarded to the underlying create-* command.

Conflict Handling:

• If you specify a language flag via adapter (e.g. javascript=true) that conflicts with the CLI choice (--typescript), Stacksmith will warn and ask for confirmation (interactive mode) or ignore the conflicting adapter flag (non-interactive mode).
• Accepted boolean forms: flag=true adds --flag; flag=false skips adding it. Any other value is passed as --flag <value>.

Examples:

# Astro strict TypeScript mode and custom template (using --with for clean syntax)
stacksmith create my-site --template astro-app --with "--template blog --typescript strict"

# Next.js with Tailwind override (forcing inclusion even if not in feature list)
stacksmith create my-app --template next-app --with "--tailwind"

# Or use full native command (infers template and project name)
stacksmith create --adapter-command "npm create astro@latest my-site -- --template blog --typescript strict"

# Legacy key=value syntax still supported
stacksmith create my-site --template astro-app --adapter-flags template=blog,typescript=strict

Direct Paste Heuristic

Stacksmith can auto-detect native create commands without requiring --adapter-command:

# Simply paste the native command as the first argument
stacksmith create npm create astro@latest my-site -- --template blog --typescript strict

# Works with any package manager
stacksmith create pnpm create next-app my-app --typescript --tailwind
stacksmith create yarn create astro my-site -- --template minimal
stacksmith create npx create-next-app@latest my-app

The command is auto-detected if it:

• Starts with a package manager (npm, pnpm, yarn, npx)
• Contains "create"
• Contains a known template (astro, next)

Dry Run Mode

Preview what would be executed without creating any files:

# See what would happen before committing
stacksmith create my-app --template next-app --with "--tailwind" --dry-run

# Output shows:
# - Parsed configuration
# - Adapter flags that would be passed
# - Conflicts detected and how they'd be resolved
# - Final command that would execute

Dry run is useful for:

• Debugging flag parsing and precedence
• Understanding conflict resolution
• Verifying adapter command construction
• Testing configurations before execution

Configuration Files

Create a .stacksmithrc file to set default preferences and avoid typing the same options repeatedly:

Local config (.stacksmithrc in project directory):

{
  "template": "react-app",
  "language": "typescript",
  "packageManager": "pnpm",
  "features": ["vitest", "biome", "tailwind", "vscode"],
  "adapterFlags": {
    "template": "minimal"
  }
}

Home config (~/.stacksmithrc):

{
  "packageManager": "pnpm",
  "language": "typescript",
  "features": ["vitest", "biome"]
}

Usage:

# Uses config file defaults, only prompts for missing fields
stacksmith create my-app

# CLI flags override config file values
stacksmith create my-app --template next-app --features storybook,playwright

# Specify custom config location
stacksmith create my-app --config ./my-config.json

Precedence (highest to lowest):

1. CLI flags (--template, --features, etc.)
2. Explicit config file (--config path/to/config.json)
3. Local .stacksmithrc (in current directory)
4. Home .stacksmithrc (~/.stacksmithrc)
5. Interactive prompts (for missing values)

Supported fields:

• template - "react-app", "next-app", "astro-app", "library", "monorepo"
• language - "typescript" or "javascript"
• packageManager - "pnpm", "npm", or "yarn"
• features - Array of feature names
• git - Boolean to enable/disable git initialization
• adapterFlags - Object with adapter-specific flags

All fields are optional. Missing fields will be prompted interactively or use CLI defaults.

📦 Current Templates

React App (Vite)

A modern React application powered by Vite:

• React 18 with TypeScript or JavaScript
• Vite for blazing fast HMR
• Modern React patterns
• Production-ready build configuration

Coming Soon:

• Next.js App
• Library Package
• Monorepo (Turborepo)

🎨 Available Features

Currently supported features you can add to your project:

• ✅ Vitest - Fast unit testing with coverage
• ✅ Biome - Lightning-fast linting and formatting
• ✅ VSCode Config - Settings and recommended extensions
• 🚧 Playwright - E2E testing (config only)
• 🚧 Storybook - Component development (config only)
• 🚧 Tailwind CSS - Utility-first CSS (config only)
• 🚧 Git Hooks - Pre-commit hooks (config only)
• 🚧 Commitizen - Conventional commits (config only)
• 🚧 Changesets - Version management (config only)
• 🚧 Turbo - Build system (config only)
• 🚧 Docker - Container setup (config only)

Note: Features marked with 🚧 generate basic configuration files but may require additional setup.

🛠 Development

Want to contribute or modify Stacksmith? Here's how to get started:

# Clone the repository
git clone https://github.com/yourusername/stacksmith.git
cd stacksmith

# Install dependencies (requires pnpm)
pnpm install

# Build the project
pnpm build

# Link for local testing
pnpm link --global

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Lint and format
pnpm lint

Project Structure

stacksmith/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── commands/           # Command implementations
│   │   └── create.ts       # Create command with prompts
│   ├── generators/         # Project generators
│   │   ├── project.ts      # Main project generator
│   │   └── features.ts     # Feature file generators
│   ├── git.ts              # Git initialization
│   ├── project-config.ts   # Configuration builder
│   ├── validation.ts       # Input validation
│   └── types.ts            # TypeScript types
├── test/                   # Comprehensive test suite
│   ├── validation.test.ts
│   ├── project-config.test.ts
│   ├── git-init.test.ts
│   ├── integration.test.ts
│   ├── cli-prompts.test.ts
│   ├── cli.test.ts
│   └── bootstrap-validation.test.ts
└── docs/                   # Additional documentation

See CONTRIBUTING.md for detailed contribution guidelines.

📚 Documentation

• Contributing Guide - How to contribute to Stacksmith
• Architecture - Technical design and decisions
• Prompts Guide - Detailed CLI prompt specifications

🗺 Roadmap

v1.0 (Current)

• ✅ React + Vite template
• ✅ TypeScript/JavaScript support
• ✅ Interactive CLI with validation
• ✅ Basic feature generation (Vitest, Biome, VSCode)
• ✅ Git initialization

v1.1 (Next)

• Complete feature implementations (Playwright, Storybook, Tailwind)
• Next.js template
• Library template
• stacksmith add command for existing projects

v2.0 (Future)

• Monorepo template with Turborepo
• CI/CD workflow generation
• Plugin system for custom templates
• Config file support for reproducible setups

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide to get started.

Development Principles

• Test-Driven Development - All features have comprehensive tests
• Type Safety - Full TypeScript with strict mode
• User Experience - Clear prompts, helpful errors, great defaults
• Extensibility - Easy to add new templates and features

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• Inquirer.js - Interactive prompts
• Vite - Build tool
• Biome - Linter and formatter
• Vitest - Testing framework

Developed with AI assistance as a productivity multiplier. All architectural decisions, testing strategies, and code validation done by humans.

---

Made with ❤️ for the JavaScript community