create-esa-stack

A CLI tool to quickly scaffold Next.js projects with ESA's preferred tech stack.

Opinionated but flexible. Starts with a robust modern foundation, then lets you pick exactly the extras you need.

Features

Every project is created with a solid baseline:

• ✅ Next.js - React framework with App Router
• ✅ TypeScript - Type-safe JavaScript
• ✅ Tailwind CSS - Utility-first CSS framework (v4)
• ✅ Biome.js - Ultra-fast linter and formatter
• ✅ React Compiler - Optimized React performance
• ✅ Turbopack - Fast bundler for development
• ✅ pnpm - Efficient package manager

Optional Integrations

During setup, you can interactively choose to add:

• 🎨 shadcn/ui - Beautiful, accessible, copy-paste components.
• 📡 TanStack Query - Powerful asynchronous state management.
• 🚦 @next/third-parties - Optimized loading for third-party scripts.
• 📧 Email (Resend + React Email) - Transactional emails with React components.
• 📦 Backend Choice - Choose your primary backend infrastructure:
  • ⚡ Supabase - Auth, DB, Realtime.
  • 🎷 Jazz.tools - Local-first sync and auth.
• 🧩 Zod - TypeScript-first schema validation with static type inference.
• 🧪 Testing Tools - Vitest & React Testing Library (Unit/Integration testing).
• 📚 Storybook - Frontend workshop for UI development (Includes testing setup).

Usage

Recommended (pnpm)

pnpm create esa-stack@latest

Other Package Managers

npm

npx create-esa-stack@latest

yarn

yarn create esa-stack

bun

bun create esa-stack

Interactive Flow

The CLI will guide you through the setup:

1. Project Name: Choose a name for your directory.
2. Scaffolding: Sets up the base Next.js application.
3. Optional Packages:
   • Install shadcn/ui? (Default: Yes)
   • Install TanStack Query? (Default: Yes)
   • Install @next/third-parties? (Default: Yes)
   • Install Email tools? (Resend + React Email) (Default: No)
   • Choose Backend? (Supabase, Jazz, or None)
   • Install Zod? (Default: Yes, skipped if Jazz is selected)
   • Install Storybook? (Default: No)
     • If Yes: Sets up Storybook environment.
     • If No: Asks to install Testing Tools (Vitest) separately.

CLI Options

You can pass the project name and options directly via CLI to skip prompts:

pnpm create esa-stack <project-name> [options]

Available Flags:

| Flag | Description | Default | | :--- | :--- | :--- | | --shadcn / --no-shadcn | Install shadcn/ui | Yes | | --tanstack-query / --no-tanstack-query | Install TanStack Query | Yes | | --next-third-parties / --no-next-third-parties | Install @next/third-parties | Yes | | --email / --no-email | Install Resend + React Email | No | | --supabase | Install Supabase (Backend) | * | | --jazz | Install Jazz.tools (Backend) | - | | --no-backend | Do not install any backend | - | | --zod / --no-zod | Install Zod | Yes | | --storybook / --no-storybook | Install Storybook | No | | --testing / --no-testing | Install Vitest + RTL | Yes | | --default, -y | Skip prompts and use defaults | - | | --help | Show help message | - |

Example:

pnpm create esa-stack my-app --supabase --no-testing -y

How It Works

The CLI wraps create-next-app with a specific set of high-performance flags:

npx create-next-app@latest <project-name> \
  --ts \
  --tailwind \
  --biome \
  --react-compiler \
  --app \
  --use-pnpm \
  --turbopack \
  --yes

After scaffolding, it programmatically installs and configures selected integrations (e.g., running shadcn init, storybook init, etc.) so you're ready to code immediately.

Contributing

Contributions are welcome!

1. Clone the repository.
2. Install dependencies: bun install
3. Run the CLI locally: bun run dev
4. Build: bun run build

License

MIT