███╗   ███╗ █████╗ ████████╗████████╗      ██╗███╗   ██╗██╗████████╗
████╗ ████║██╔══██╗╚══██╔══╝╚══██╔══╝      ██║████╗  ██║██║╚══██╔══╝
██╔████╔██║███████║   ██║      ██║   █████╗██║██╔██╗ ██║██║   ██║
██║╚██╔╝██║██╔══██║   ██║      ██║   ╚════╝██║██║╚██╗██║██║   ██║
██║ ╚═╝ ██║██║  ██║   ██║      ██║         ██║██║ ╚████║██║   ██║
╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝      ╚═╝         ╚═╝╚═╝  ╚═══╝╚═╝   ╚═╝

A CLI tool for scaffolding Next.js projects the way I like 'em.

Warning

I am no longer maintaining this project. I've trying to expand out from the NextJS ecosystem, and have been learning tons of new tools and technologies! There's so many fun project out there beyond this; go explore!

Features

• Wickedly Fast Setup - Under 30 seconds to a fully wired Next.js starter
• Minimal Choices - Three streamlined prompts: backend setup, database provider, and tooling preferences
• Opinionated Defaults - Pre-configured with sensible defaults and best practices
• Backend Bundles - Choose "DB + Drizzle + BetterAuth" for full-stack or "None" for frontend-only
• Zero Configuration - Strict linting, Prettier, pre-commit hooks, and CI rules included
• Type-Safe Environment - Zod-validated env variables that fail fast on missing config
• Ready for Deployment - Tailwind, VSCode settings, and production optimizations included

...why?

I've probably started and abandoned a dozen Next.js projects. The commonality between them is that the first hour or two of a given project is spent setting up the same things over and over again. This tool aims to automate that setup process with the components and configurations I prefer, so I can focus on building features instead of boilerplate.

Also, because enforcing harsh linting rules on hackathon teammates is more justafiable when "it came installed like that".

Installation

npx matt-init@latest [project-name] [options]

Usage

Interactive Mode (Recommended)

npx matt-init@latest

This will prompt you for:

• Project name - What to call your app
• Backend setup - Choose from:
  • DB + Drizzle + BetterAuth - Full-stack with database, ORM, and authentication
  • Supabase - (coming soon)
  • None - Frontend-only
• Database provider - If you chose the full-stack option:
  • Turso (SQLite) - Edge database (implemented)
  • Neon (Postgres) - (coming soon)
  • Docker Postgres - (coming soon)
• Nix flake - Optional reproducible dev environment
• Install dependencies - Run pnpm install automatically
• VS Code settings - Setup workspace settings and recommended extensions
• Git repository - Initialize git with initial commit

Command Line Options

matt-init [project-name] [options]

Options:
  --no-git      Skip git initialization
  --no-install  Skip package installation
  --no-nix      Skip Nix flake for environment management
  --no-vscode   Skip VS Code settings setup
  -y, --default Use defaults, skip prompts
  --ci          Run in CI mode (non-interactive, test mode)
  -V, --version Display version number
  -h, --help    Display help

Examples

# Create a new project with prompts (recommended)
npx matt-init@latest my-awesome-app

# Create with defaults (frontend-only, no prompts)
npx matt-init@latest my-app --default

# Create without git and dependency installation
npx matt-init@latest my-app --no-git --no-install

# Create without Nix support (Nix is disabled by default)
npx matt-init@latest my-app --no-nix

What's Included

Every generated project includes:

Core Stack

• Next.js 15 - React framework with App Router
• TypeScript - Type safety
• Tailwind CSS - Utility-first CSS framework
• ESLint - Code linting with @antfu/eslint-config

Environment & Tooling

• Zod-validated environment variables - Type-safe env configuration
• VSCode settings - Optimized workspace configuration
• VSCode extensions - Recommended extensions for the stack

Optional Addons

• Full-Stack Backend - Turso database + Drizzle ORM + BetterAuth authentication
• Supabase Integration - (coming soon)
• Nix Flake - Reproducible development environment

Project Structure

Generated projects roughly follow this structure:

my-project/
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   └── matt-init-banner.tsx
│   └── lib/
│       ├── env.ts
│       └── try-parse-env.ts
├── .vscode/               # (if VSCode setup chosen)
│   ├── extensions.json
│   └── settings.json
├── flake.nix              # (if Nix enabled)
├── drizzle.config.ts      # (if backend setup chosen)
├── .env                   # (if backend setup chosen)
├── .env.example
├── eslint.config.mjs
├── next.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.json

Development Status

Implemented Features

Core (Every Project):

• ESLint + Prettier configuration
• Custom Next.js app with banner
• Zod-validated environment variables
• VS Code workspace settings
• Tailwind CSS setup
• TypeScript configuration

Optional (Behind Flags or Prompts):

• Full-stack backend (Turso + Drizzle + BetterAuth)
• Nix development environment (--nix flag)
• Git repository initialization
• Dependency installation
• Docker Postgres support
• Custom README generation

In Progress

• Improved CI/CD templates

Roadmap

Backend Options:

• Supabase integration
• Neon (Postgres) support

Future Flags:

• --shadcn for UI components
• --auth-only for auth without ORM

Development

Prerequisites

• Nix

Feel free to go install all the project dependencies manually if you don't want to use Nix, but I ain't telling you how to do that. This is a Nix-first project baby.

Setup

# Clone the repository
git clone <repository-url>
cd matt-init

# Switch to the development shell
nix develop

# Install dependencies
pnpm install

# Run the tool in development mode!
pnpm dev:cli

Scripts

• pnpm build:cli - Compile CLI TypeScript to JavaScript
• pnpm dev:cli - Run CLI in development mode with ts-node
• pnpm test:cli - Test the CLI by creating a test project
• pnpm lint:cli - Run ESLint on CLI
• pnpm --filter ./cli lint:fix - Fix CLI ESLint issues automatically

License

MIT

Acknowledgements

• Thanks to @antfu for the ESLint config
• Shoutout to @w3cj from the Syntax team for general project setup advice, and the try-parse-env.ts script
• Quick mention to create-t3-app for pointing me in the right direction architecture-wise