create-next-quick

create-next-quick

The fastest and most configurable way to spin up a new Next.js project

A powerful CLI tool that lets you instantly create a new Next.js project with a highly customized and clean setup.

---

Table of Contents

• Why create-next-quick?
• Features
• Quick Start
• Usage
  • Basic Usage
  • Interactive Mode
  • Interactive Prompts
  • Example Walkthrough
• Configuration Options
• Advanced Features
  • Authentication Setup
  • Testing Frameworks
  • Docker Support
• Prerequisites
• Available Scripts
• Testing
• Troubleshooting
• Contributing
• Show Your Support
• License

---

Why create-next-quick?

create-next-quick is a powerful, lightweight alternative to create-next-app, designed for developers who want more control and speed right from the start.

Comparison with create-next-app

Feature	create-next-quick	create-next-app
Multi-page Generation	✅ Yes (e.g., home, about, contact)	❌ No
ORM Support	✅ Yes (Prisma, Drizzle)	❌ No
Linter Choice	✅ Yes (ESLint, Biome)	❌ ESLint only
Shadcn UI Auto-Setup	✅ Yes (non-interactive)	❌ No
Authentication Integration	✅ Yes (NextAuth, Clerk, Lucia)	❌ No
Testing Framework Setup	✅ Yes (Vitest, Jest)	❌ No
Docker Configuration	✅ Yes (Dockerfile + .dockerignore)	❌ No
Clean Project Start	✅ Yes (removes boilerplate & default assets)	❌ No
Package Manager Detection	✅ Yes (npm, yarn, pnpm)	✅ Yes
Robust Error Handling	✅ Yes (retries, cleanup, clear tips)	❌ Basic
Interactive Mode	✅ Yes (add features to existing projects)	❌ No

---

Features

Project Scaffolding

• CLI Argument for Project Name: Skip the project name prompt by passing it as an argument
• Custom Page Generation: Create multiple pages at once from the CLI
• Clean Project Setup: Automatically removes the default favicon, clears the public folder, and provides clean page.tsx and layout.tsx files
• Safe Project Creation: Prevents accidental overwrites by checking if the target directory is empty
• Conditional API Route Deletion: Removes the default hello.js API route when not needed

Tooling & Integrations

• Package Manager Detection: Auto-detects npm, yarn, and pnpm
• Linter Support: Choose between ESLint, Biome, or no linter
• ORM Support: Integrated setup for Prisma or Drizzle (with TypeScript/JavaScript support)
• Shadcn UI: Automatically installs and configures Shadcn UI non-interactively
• TypeScript CSS Module Support: Generates global.d.ts to provide type declarations for CSS imports
• Authentication: Integrated setup for NextAuth.js, Clerk, or Lucia with middleware and API routes
• Testing: Ready-to-use configuration for Vitest or Jest with React Testing Library
• Docker: Auto-generated Dockerfile and .dockerignore for containerized deployments

Developer Experience

• Robust Error Handling: Automatic retries for failed installs, intelligent cleanup of incomplete projects, and actionable troubleshooting tips
• Automated CI/CD Feedback: Get automated comments on the test status of your Pull Requests
• Interactive Mode: Add features to existing Next.js projects without starting from scratch
• Zero External Dependencies: Uses custom lightweight prompt implementation (no inquirer dependency)

---

Quick Start

No global installation needed. Run it instantly with npx:

npx create-next-quick my-app
cd my-app
pnpm run dev

---

Usage

Basic Usage

npx create-next-quick [project-name]

If you omit [project-name], the tool will prompt you for it. Use . to create in the current directory (must be empty).

Interactive Mode (for existing projects)

Already have a Next.js project? Use the -i or --interactive flag to run create-next-quick on your existing project and add new features without starting from scratch.

cd my-existing-nextjs-project
npx create-next-quick -i

When you run in interactive mode, the tool will:

1. Detect Your Project's Setup: Automatically detects if you're using TypeScript, the src directory, the app directory, and Tailwind CSS
2. Skip Project Creation: It will not run create-next-app or remove any existing files
3. Prompt for Additions: It will only ask you what you want to add to your project, such as new pages, a linter, an ORM, or Shadcn UI

This is perfect for when you want to add a new feature to your project and want to use the same streamlined setup process.

Interactive Prompts

The CLI will guide you through the following options:

Prompt	Description	Default
Package Manager	Auto-detects installed npm, yarn, pnpm	pnpm
TypeScript	Use TypeScript for type safety	Yes
Tailwind CSS	Use Tailwind CSS for styling	Yes
src/ Directory	Use the src/ directory for project structure	Yes
App Router	Use the Next.js App Router	Yes
Pages	Enter page names to create (comma-separated)	none
Linter	Choose a linter (ESLint, Biome)	none
ORM	Choose an ORM (Prisma, Drizzle)	none
Testing	Choose a testing framework (Vitest, Jest)	none
Authentication	Choose auth solution (NextAuth, Clerk, Lucia)	none
Shadcn UI	Automatically install and set up Shadcn UI	Yes
Docker	Add Docker support with Dockerfile	No

Example Walkthrough

$ npx create-next-quick my-portfolio

✔ Using default for package manager: pnpm
✔ Using default for TypeScript: Yes
✔ Using default for Tailwind CSS: Yes
✔ Using default for src directory: Yes
✔ Using default for app directory: Yes
? Enter the names of the pages you want to create (comma-separated): home, about, contact
✔ Using default for linter: none
✔ Using default for ORM: none
✔ Using default for testing: none
✔ Using default for authentication: none
✔ Using default for Shadcn UI: Yes
✔ Using default for Docker: No

---

Configuration Options

Linters

ESLint

• Pre-configured with Next.js recommended rules
• Automatically installed if selected

Biome

• Fast, modern linter and formatter
• Zero-config setup with biome.json
• Includes pre-commit hooks with Husky

ORMs

Prisma

• Automatically installs prisma and @prisma/client
• Initializes Prisma with prisma init
• Creates a singleton Prisma client in src/lib/prisma.ts (or .js)
• Generates .env file with DATABASE_URL placeholder
• Supports both TypeScript and JavaScript projects

Drizzle

• Installs drizzle-orm, drizzle-kit, and @vercel/postgres
• Creates drizzle.config.ts (or .js) with PostgreSQL dialect
• Generates example schema in src/db/schema.ts (or .js)
• Supports both TypeScript and JavaScript projects
• Includes .env file with DATABASE_URL placeholder

---

Advanced Features

Authentication Setup

NextAuth.js (v5 Beta)

Automatically sets up:
- src/lib/auth.ts (or .js) with credentials provider
- src/app/api/auth/[...nextauth]/route.ts (or .js)

Clerk

Automatically sets up:
- middleware.ts (or .js) with Clerk middleware
- .env with NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY placeholders

Lucia

Installs core package
- Provides instructions for adapter setup

Testing Frameworks

Vitest

Automatically configures:
- vitest.config.ts (or .js) with React plugin
- vitest.setup.ts (or .js) with jest-dom
- package.json test script
- ES module compatible path resolution

Jest

Automatically configures:
- jest.config.js with Next.js integration
- jest.setup.js with jest-dom
- package.json test script
- TypeScript support (if enabled)

Docker Support

Generates production-ready Docker configuration:

• Multi-stage build for optimized image size
• Standalone output mode in next.config.mjs
• .dockerignore for efficient builds
• Node.js 20 Alpine base image

---

Prerequisites

• Node.js: v20.0.0 or higher

Check your Node.js version:

node --version

---

Available Scripts

Once your project is created, you can use the following commands:

pnpm	npm	yarn	Description
pnpm dev	npm run dev	yarn dev	Starts the development server
pnpm build	npm run build	yarn build	Builds the app for production
pnpm start	npm start	yarn start	Starts the production server
pnpm lint	npm run lint	yarn lint	Runs the linter (if configured)
pnpm test	npm test	yarn test	Runs tests (if configured)

---

Testing

The test suite is dynamically generated to ensure comprehensive coverage.

Generate Test Cases

npm run test:generate

Run Tests

npm test

Run Interactive Tests

npm run test:interactive

---

Troubleshooting

Common Issues

Installation Fails

# Check your internet connection
# Ensure package manager is up to date
npm install -g npm@latest
# or
pnpm add -g pnpm@latest

Permission Errors

If you encounter permission errors, avoid using sudo as it can cause npm cache permission issues and create root-owned files in user directories. Instead, try these safer alternatives:

# Option 1: Use a Node version manager (recommended)
# Install nvm (https://github.com/nvm-sh/nvm) or fnm (https://github.com/Schniz/fnm)
# Then reinstall Node.js through the version manager

# Option 2: Fix npm permissions by setting a user-local prefix
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your ~/.bashrc or ~/.zshrc:
# export PATH=~/.npm-global/bin:$PATH

# Option 3: Ensure you're creating the project in a user-owned directory
cd ~/projects  # or any directory you own
npx create-next-quick my-app

TypeScript Errors After Setup

# Regenerate types
pnpm run build

Prisma Client Not Found

# Generate Prisma client
npx prisma generate

Port Already in Use

# Kill the process using port 3000
# On macOS/Linux:
lsof -ti:3000 | xargs kill -9
# On Windows:
netstat -ano | findstr :3000
taskkill /PID <PID> /F

---

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch: git checkout -b feature/your-feature-name
3. Make your changes and commit them: git commit -m "feat: Add some amazing feature"
4. Push to the branch: git push origin feature/your-feature-name
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/gaureshpai/create-next-quick.git
cd create-next-quick

# Install dependencies
pnpm install

# Run tests
pnpm test

# Generate test cases
pnpm run test:generate

# Lint code
pnpm run lint

Commit Convention

We follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• chore: Maintenance tasks
• refactor: Code refactoring
• test: Test updates

---

Show Your Support

Give a ⭐️ if this project helped you!

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Contributors

---

Documentation • Report Bug • Request Feature