create-next-pro-cli

create-next-pro generates and evolves Next.js 16 projects with TypeScript, App Router, React 19, Tailwind CSS 4, next-intl, and Auth.js.

The launcher uses Bun when available and automatically falls back to Node.js. No runtime selection is persisted. Generated projects are validated with Bun, npm, and pnpm.

Purpose

create-next-pro provides a reproducible, production-oriented Next.js foundation and commands to evolve it without manually relocating files. The scaffolder separates App Router routes, interfaces under src/ui, translated messages, and application libraries to keep the structure clear as the application grows.

The CLI is built around a runtime-independent core, injectable terminal and file-system adapters, and generators confined to the project root. The distributed template includes internationalization, authentication, a CSP policy, environment validation, and automated quality checks.

Main features

• direct or interactive Next.js 16 project creation;
• Bun-first CLI execution with an automatic Node.js fallback;
• generated projects compatible with Bun, npm, and pnpm;
• generation of pages, components, libraries, and API routes;
• addition of next-intl locales and messages;
• direct or interactive page removal with a tree-based selector;
• nested routes and interfaces using Parent.Child notation;
• customizable import aliases such as @/* or @core/*;
• dedicated Bash and Zsh completion;
• confined file operations and allowlist-based template copying;
• Auth.js, CSP, environment validation, Vitest, and Playwright in the template.

Requirements

• Node.js 24 or later, or Bun 1.3 or later, to run the CLI.
• Bun 1.3+, the npm version bundled with Node.js 24+, or pnpm 11+ for generated projects.

Installation

bun install --global create-next-pro-cli
# or
npm install --global create-next-pro-cli
# or
pnpm add --global create-next-pro-cli

Without a global installation:

bunx create-next-pro-cli my-app
npx create-next-pro-cli my-app
pnpm dlx create-next-pro-cli my-app

On first launch, the onboarding assistant offers to install Bash or Zsh completion. Run create-next-pro --reconfigure to start the assistant again without duplicating the shell configuration.

Create a project

create-next-pro my-app
cd my-app

Then install dependencies with your preferred package manager:

bun install && cp .env.example .env && bun run dev
# or
npm install && cp .env.example .env && npm run dev
# or
pnpm install && cp .env.example .env && pnpm run dev

The creation result reports .env.example explicitly and provides the same local-development commands in both human and JSON output.

An existing destination is rejected by default. --force only permits replacement of the requested child destination:

create-next-pro my-app --force

Without a project name, the CLI opens the interactive assistant. The import alias must follow the <prefix>/* form, such as @/* or @core/*. It is written to tsconfig.json and cnp.config.json, then reused by the generators.

Project evolution commands

Run the following commands from the root of a generated project.

# Simple or nested pages
create-next-pro addpage profile --area public
create-next-pro addpage account.security --area user
create-next-pro addpage operations.audit --area admin

# Global components or components attached to a page
create-next-pro addcomponent Alert
create-next-pro addcomponent PasswordForm --page account.security --area user
create-next-pro addcomponent AuditPanel --page operations.audit --area admin

# Libraries and modules
create-next-pro addlib analytics
create-next-pro addlib analytics.trackEvent

# Routes API
create-next-pro addapi health

# Locales and translations
create-next-pro addlanguage de
create-next-pro addtext dashboard.welcome "Welcome"

# Direct removal
create-next-pro rmpage account.security --area user
create-next-pro rmpage operations.audit --area admin

# Tree-based autocomplete menu with confirmation
create-next-pro rmpage

Every page belongs to an explicit route area. Use --area public for anonymous routes, --area user for authenticated routes, and --area admin for request-bound routes protected by the server-only administrator allowlist. There is no default area. Direct addpage and rmpage commands require it, as does addcomponent --page; interactive addpage asks for it and the rmpage menu groups pages by area. Route groups do not alter the public URL, so the same logical page name cannot exist in multiple areas. The official areas are a closed set, not an extensible RBAC system.

addlib library.module preserves an existing library index byte for byte. It appends one direct value or type re-export only after verifying the index and module with TypeScript. If the public export is already present, the command returns unchanged; ambiguous modules, conflicting exports, invalid TypeScript, and concurrent edits fail before the index is modified. Projects affected by the historical 0.1.20–0.1.34 barrel-reduction defect should follow the recovery note in CHANGELOG.md.

addlanguage copies every message file from the configured default locale. The command reports each copied path and emits a required translate next step: the copied source-language text must be translated before the locale is ready to ship.

addpage creates layout, page, and loading files by default. Available long options are --layout, --page, --loading, --not-found, --error, --global-error, --route, --template, and --default. The historical short forms remain available.

Generated page-level layouts accept only children because they do not read route parameters. If a customized Next.js 16 layout needs the locale, make the component asynchronous, type params as Promise<{ locale: string }> and await it before use. Projects generated with [email protected] may contain the obsolete synchronous params: { locale: string } signature: remove that property when it is unused, or migrate it to the asynchronous contract.

rmpage only lists routes that contain an actual page.tsx in the (public), (user), or (admin) route group. Technical directories remain hidden. Removal is confined to the selected area and project, and it preserves shared parent directories and unrelated files.

Generated project architecture

The Next.js route and its interface are separate: src/app owns routing while src/ui owns page components. Translations remain organized by locale and domain.

my-app/
├── .agents/
│   └── skills/
│       ├── create-next-pro-create-project/
│       ├── create-next-pro-addpage/
│       └── ...
├── .env.example
├── .gitignore
├── .prettierignore
├── AGENTS.md
├── bun.lock
├── cnp.config.json
├── messages/
│   ├── en/
│   │   ├── _global_ui.json
│   │   ├── _home.json
│   │   ├── dashboard.json
│   │   ├── login.json
│   │   ├── register.json
│   │   ├── settings.json
│   │   └── userInfo.json
│   ├── en.ts
│   ├── fr/
│   │   └── ...
│   └── fr.ts
├── public/
│   ├── logo.png
│   └── logo.svg
├── src/
│   ├── app/
│   │   ├── [locale]/
│   │   │   ├── (public)/
│   │   │   │   ├── _home/
│   │   │   │   ├── login/
│   │   │   │   └── register/
│   │   │   ├── (user)/
│   │   │   │   ├── dashboard/
│   │   │   │   ├── settings/
│   │   │   │   └── userInfo/
│   │   │   ├── (admin)/
│   │   │   │   └── layout.tsx
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   ├── api/auth/[...nextauth]/route.ts
│   │   └── styles/globals.css
│   ├── lib/
│   │   ├── auth/
│   │   ├── i18n/
│   │   ├── security/csp.ts
│   │   └── utils.ts
│   ├── ui/
│   │   ├── _global/
│   │   ├── _home/
│   │   ├── dashboard/
│   │   ├── login/
│   │   ├── register/
│   │   ├── settings/
│   │   └── userInfo/
│   ├── auth.ts
│   ├── config.ts
│   ├── env.ts
│   └── proxy.ts
├── tests/
│   ├── consumer/
│   ├── e2e/
│   ├── rendering/
│   └── unit/
├── scripts/
│   ├── audit.ts
│   └── package-manager.ts
├── next.config.ts
├── package.json
├── playwright.config.ts
├── pnpm-workspace.yaml
├── tsconfig.json
└── vitest.config.ts

Template working files (.env, the nested Git repository, caches, screenshots, and test results) are not copied into generated projects. The CLI creates cnp.config.json with the project name and selected alias.

Generated projects also include concise root guidance in AGENTS.md and eight instruction-only command skills under .agents/skills. Agents should prefer the deterministic --json contract and read the matching skill before invoking a project mutation.

CLI architecture

create-next-pro-cli/
├── bin.bun.ts
├── bin.node.ts
├── src/
│   ├── cli/
│   │   ├── completion.ts
│   │   ├── onboarding.ts
│   │   ├── output.ts
│   │   └── registry.ts
│   ├── core/
│   │   ├── contracts.ts
│   │   ├── operations.ts
│   │   ├── page-catalog.ts
│   │   ├── project-paths.ts
│   │   └── template-manifest.ts
│   ├── lib/
│   │   ├── addApi.ts
│   │   ├── addComponent.ts
│   │   ├── addLanguage.ts
│   │   ├── addLib.ts
│   │   ├── addPage.ts
│   │   ├── addText.ts
│   │   ├── createProject.ts
│   │   └── rmPage.ts
│   ├── release/
│   │   └── model.ts
│   ├── runtime/
│   │   └── node-context.ts
│   ├── index.ts
│   └── scaffold.ts
├── templates/
│   ├── Component/
│   ├── Page/
│   ├── Projects/default/
│   ├── Api/
│   └── Lib/
├── create-next-pro-completion.sh
├── create-next-pro-completion.zsh
├── package.json
└── tsup.config.ts

The CLI registry resolves commands to a shared asynchronous interface. The core defines contracts, the page catalog, and path boundaries; runtime adapters provide prompts, console access, and file-system operations. Bun and Node.js bundles are built separately and selected by the dist/create-next-pro launcher.

Global options

--help          Show help
--version, -v   Show the version
--json          Emit one deterministic JSON document
--reconfigure   Run CLI configuration again
--force         Replace an existing project destination

--json can appear before or after a command. It disables prompts, colors, banners, and incidental logs. Standard output contains exactly one JSON document followed by a newline, while standard error remains empty even when the command fails. Internal shell completion continues to use its separate line-based protocol.

Human and agent output

Human output names every created, copied, updated, deleted, unchanged, or skipped resource with an absolute path. It ends with a summary and only the next steps that are still required. For example, adding a locale clearly reports that its messages were copied from the source locale:

COPIED translation-messages: /workspace/my-app/messages/de/dashboard.json from /workspace/my-app/messages/en/dashboard.json (locale="de", sourceLocale="en")
UPDATED messages-registry: /workspace/my-app/src/lib/i18n/messages.ts
SUCCESS: Added locale "de" by copying 7 files from "en".
NEXT [translate]: Translate every copied message from en to de; the copied text is not ready for delivery.
  /workspace/my-app/messages/de/dashboard.json

Agentic usage adds --json:

create-next-pro addapi health --json

The versioned document has stable status, event, next-step, and error fields:

{
  "schemaVersion": 1,
  "command": "addapi",
  "status": "success",
  "exitCode": 0,
  "summary": "Added API route \"health\".",
  "projectRoot": "/workspace/my-app",
  "events": [
    {
      "sequence": 1,
      "action": "created",
      "resource": "directory",
      "role": "api-directory",
      "scope": "project",
      "path": "src/app/api/health"
    },
    {
      "sequence": 2,
      "action": "created",
      "resource": "file",
      "role": "api-route",
      "scope": "project",
      "path": "src/app/api/health/route.ts"
    }
  ],
  "nextSteps": [
    {
      "kind": "review",
      "required": true,
      "message": "Replace the example response and review validation and authentication.",
      "paths": [
        {
          "scope": "project",
          "path": "src/app/api/health/route.ts"
        }
      ]
    }
  ],
  "error": null
}

Paths inside events and next steps are relative to their named scope. Applicable absolute roots are exposed as projectRoot, configRoot, and homeRoot. Events never contain file contents, environment values, credentials, or secrets.

Command statuses are success, unchanged, cancelled, and failed. Successful mutations, idempotent no-op results, and user cancellations exit with code 0; only failed exits with code 1. Stable error codes include INVALID_ARGUMENT, CONFIG_NOT_FOUND, I18N_DISABLED, TARGET_EXISTS, TARGET_NOT_FOUND, TEMPLATE_MISSING, UNSAFE_PATH, INCONSISTENT_ROUTE, INCONSISTENT_LOCALE, INCONSISTENT_LIBRARY_INDEX, INCONSISTENT_LIBRARY_MODULE, CONCURRENT_MODIFICATION, FILESYSTEM_ERROR, INTERACTIVE_INPUT_REQUIRED, and ONBOARDING_REQUIRED.

Interactive input is never attempted in JSON mode. Pass every required argument explicitly. On a new machine, run the CLI once without --json to complete onboarding; --reconfigure --json is intentionally rejected.

Environment and security

Generated projects contain only the canonical .env.example, never the template's local .env or other environment copies. Copy it before configuring Auth.js:

cp .env.example .env

The Google and Auth.js values shipped in .env.example are intentionally public, limited development credentials. Replace all of them before production use. Configure AUTH_ADMIN_EMAILS as a comma-separated server-side allowlist before adding administrator routes; an absent, empty, or invalid allowlist denies every administrator request. Nested Git repositories, caches, installed dependencies, Playwright artifacts, agent context, the local .env, and every non-canonical .env* file are excluded from generated projects and the npm package. For checks without authentication, use AUTH_DISABLED=true.

Quality

In the CLI repository:

bun install --frozen-lockfile
bun run check

In a generated project, the same scripts work with all three package managers:

bun run check
npm run check
pnpm run check

Validation covers formatting, linting, TypeScript, Vitest, the Next.js build, and the rendering contract. Use npm pack --dry-run --json to inspect the CLI's distributable contents.

The template source keeps one official bun.lock. npm and pnpm create their manager-specific lockfiles only in consumer worktrees; .prettierignore keeps those generated locks outside formatting checks. The generated GitHub Actions workflow validates all three managers independently and runs its npm job without Bun installed. Explicit npm allowScripts and pnpm allowBuilds policies limit native install scripts to the four dependencies required by the toolchain.

Development

git clone https://github.com/Rising-Corporation/create-next-pro-cli.git
cd create-next-pro-cli
bun install --frozen-lockfile
bun run build
bun link
create-next-pro --help

MIT licensed. Contribution guidelines are available in CONTRIBUTING.md. The complete public capability contract is maintained in FUNCTIONALITY.md, and vulnerabilities must follow the private process in SECURITY.md.