Basic Next.js Starter

A modular Next.js starter built for real product code, not throwaway demos.
Uses App Router + TypeScript + feature-first modules with clear boundaries between UI, domain logic, and configuration.

Scaffold a New Project

npx create-basic-nextjs my-app

You can also pass a relative or absolute path:

npx create-basic-nextjs ./projects/my-app

This copies the full starter template into a new directory, updates package.json with your project name, and strips out template-only internals (the CLI itself, .git, node_modules, .env files). You end up with a clean, ready-to-develop project.

Tech Stack

• Next.js 16 (App Router)
• React 19 + TypeScript
• Tailwind CSS v4
• shadcn/ui (Radix UI + CVA)
• ESLint + Prettier

Getting Started

After scaffolding:

cd my-app
npm install

Create your environment file (not copied by the CLI):

cp .env.example .env.local

Start the dev server:

npm run dev

App runs at http://localhost:3000.

Environment Variables

Configure in .env.local:

| Variable | Description | Example | |-----------------|--------------------------------------------------|----------------------------| | APP_NAME | Display name of the app | "My App" | | APP_VERSION | App version string | 1.0.0 | | COOKIE_PREFIX | Prefix for all cookie names (avoids collisions) | "my-app-" | | BASE_API_URL | Base URL for the API endpoint | https://api.example.com |

.env.local is excluded from the CLI copy. You must create it manually in your generated project.

Available Scripts

| Script | Description | |---------------------|--------------------------| | npm run dev | Start development server | | npm run build | Create production build | | npm run start | Run production server | | npm run lint | Run ESLint |

Project Structure

See STRUCTURE.md for a full breakdown of the folder layout, module anatomy, routing conventions, config layer, and how to add new features.

CLI Reference

Usage

# Via npx (recommended)
npx create-basic-nextjs <project-name>

# Via npx with a path
npx create-basic-nextjs path/to/my-app

# Local (inside this repo)
npm run scaffold -- <project-name>

What Gets Copied

Everything in the template root except:

• .git/
• .next/
• node_modules/
• dist/
• coverage/
• cli/
• .env / .env.local
• .DS_Store

Project Name Normalization

The generated package.json name is derived from the directory name: lowercased, non-alphanumeric characters replaced with -, and leading/trailing dashes stripped.
Example: My App 2 → my-app-2.

Error Cases

| Situation | Behavior | |-------------------------------|-----------------------------------------------| | No argument provided | Prints usage hint, exits with code 1 | | Argument starts with - | Prints usage hint, exits with code 1 | | Target directory already exists | Prints path, exits with code 1 |

Contributing & Publishing

Bump the version:

npm version patch

Publish:

npm publish --access public

Users can then scaffold with:

npx create-basic-nextjs my-app