Nextron CLI

Generate a typed application from the stack and infrastructure you choose, then extend it with feature-oriented modules you own.

The first prompt picks the stack:

• Next.js — an App Router full-stack app.
• Vite + Node — an Express + TypeScript API, optionally in a pnpm monorepo with a Vite + React frontend.
• React Native (Expo) — an Expo SDK 56 app (Expo Router + NativeWind), standalone or in a monorepo with the same Express backend.

Nextron creates ordinary source code. It does not introduce a runtime framework or require the CLI after generation — the generated application is plain TypeScript that you inspect, customize, and deploy like any other project.

Requirements

• Node.js 20 or newer.
• One of pnpm, npm, Yarn, or Bun for installing the generated project's dependencies.

Quick start

Run the latest public release without installing it globally:

npx @edwinfom/nextron@latest create my-app

Or install the CLI globally:

npm install --global @edwinfom/nextron
nextron create my-app

Then start the generated application:

cd my-app
cp .env.example .env.local
pnpm dev

Replace the example values in .env.local before using modules that connect to external services.

What it generates

Depending on the stack:

• Next.js — App Router with strict TypeScript and Tailwind CSS v4; optional Drizzle/Prisma, Better Auth/Clerk/NextAuth, tRPC, AI SDK, Stripe, Polar, Inngest, and dashboard modules. Env validated in src/env.ts.
• Vite + Node — an Express + TypeScript API (MongoDB/Mongoose or SQL Server/mssql), optional JWT auth, AI, tRPC, Inngest, and Stripe/Polar payments, optionally in a monorepo with a Vite + React + Tailwind frontend. Env validated in src/config/env.ts.
• React Native (Expo) — an Expo SDK 56 app (Expo Router + NativeWind) with mobile screens for auth, payments, AI chat, and tRPC; standalone or in a monorepo with the Express backend. Env validated in src/shared/env.ts (EXPO_PUBLIC_* only).

Every stack also generates:

• A .env.example listing every variable the selected modules need.
• AGENTS.md and CLAUDE.md instructions tailored to the selected stack, so coding agents understand the project immediately.
• nextron.config.ts, which records the generated project configuration for later module additions.

Commands

nextron [command]

Commands:
  create [name]   Create a new Nextron application
  add <module>    Add a module to an existing Nextron application

Global flags:
  --help          Show usage for the CLI or a subcommand
  --version       Print the installed CLI version

Running nextron without a subcommand starts the same workflow as nextron create.

nextron create

nextron create customer-portal

If no name is supplied, the CLI asks for one. Project names may contain lowercase letters, numbers, hyphens, and underscores.

The first prompt selects the stack — Next.js, Vite + Node, or React Native (Expo). The remaining prompts depend on that choice; the tables below cover the Next.js flow. For the other stacks, see the Express backend guide and the Expo guide.

For a Next.js project the interactive setup then asks for:

| Choice | Options | | --- | --- | | ORM | Drizzle, Prisma, none | | Database | PostgreSQL, SQLite, MySQL, none | | PostgreSQL provider | Neon, Supabase, local/Docker | | Authentication | Better Auth, Clerk, NextAuth, none | | Additional modules | tRPC, AI, Stripe, Polar, Inngest, dashboard | | AI provider | Anthropic, OpenAI, DeepSeek, Google | | Package manager | pnpm, npm, Yarn, Bun | | Dependency installation | Install immediately or skip |

Notes on the prompts:

• The dashboard option is shown only when authentication is enabled, because its routes and session UI require an authentication provider.
• The AI provider prompt appears only when the AI module is selected.
• The PostgreSQL provider prompt appears only when PostgreSQL is selected; the chosen provider decides which database client is generated (for example, the Neon serverless driver versus node-postgres).
• The package manager is auto-detected from how you invoked the CLI (npm_config_user_agent) and from the tools available on your machine; the detected option is preselected but you can pick another.
• Cancelling any prompt (Ctrl+C) exits cleanly. No files are written until every prompt is answered and the summary is shown.

Example session

Project name       customer-portal
ORM                Drizzle
Database           PostgreSQL
Provider           Neon
Authentication     Better Auth
Modules            tRPC, Stripe, Dashboard
Package manager    pnpm
Install now        Yes

Installation behavior

When you choose to install immediately, Nextron runs the selected package manager for you. With pnpm and npm it passes --prefer-offline, so packages already in your local store or cache are reused instead of re-downloaded — repeat generations on the same machine are significantly faster. Install output is captured quietly; if the install fails, the captured error is shown and you can re-run the install manually.

nextron add

Run add from the root of a generated project — the directory containing nextron.config.ts:

nextron add stripe

The command:

1. Reads the existing Nextron configuration.
2. Validates the requested module against the modules already installed.
3. Resolves required modules automatically and shows everything that will be added before asking for confirmation.
4. Preserves existing files instead of overwriting them — conflicting files are skipped with a warning.
5. Adds the module dependencies to package.json.
6. Updates nextron.config.ts.
7. Offers to install the new packages with the package manager recorded in the config (falling back to lockfile detection).
8. Prints any environment variables the new module needs.

Module names

| Name | Generated capability | | --- | --- | | database | Configured Drizzle or Prisma database layer | | auth | Configured Better Auth, Clerk, or NextAuth integration | | trpc | tRPC v11 router, procedure example, client, and provider | | ai | AI SDK provider, streaming route, and starter chat interface | | stripe | Stripe server client and webhook handling | | polar | Polar server client, checkout, customer portal, and webhook handling | | inngest | Inngest client, function registry, and route handler | | dashboard | Protected routes, navigation shell, overview, and settings |

Modules for the Vite + Node (Express) and React Native (Expo) stacks — backend files target the API, mobile screens target the Expo app:

| Name | Generated capability | | --- | --- | | express-database | MongoDB (Mongoose) or SQL Server (mssql) connection, model, service, and seeder (backend only) | | express-auth | JWT register/login, bcrypt, Bearer middleware — plus Expo sign-in/up screens + secure-store session | | express-ai | Streaming /api/ai/chat endpoint — plus an Expo chat screen | | express-trpc | tRPC v11 router over Express — plus a typed Expo client | | express-inngest | Inngest client, function registry, and route handler (backend only) | | stripe-express | Stripe checkout + signature-verified webhook — plus a native Expo PaymentSheet screen | | polar-express | Polar checkout, portal + signature-verified webhook — plus an Expo hosted-checkout screen |

Module compatibility rules

• dashboard requires auth. It cannot be added when auth is none; configure authentication when creating the project.
• Better Auth and NextAuth require a database; the CLI reports this before writing files.
• Required modules are pulled in automatically: adding dashboard to a project without auth configured lists both and asks once.
• Incompatibility checks cover the entire resolved set — including modules added automatically as requirements, not just the one you named.
• Modules are stack-aware: Next.js modules cannot be added to a Vite + Node or Expo project, and *-express modules cannot be added to a Next.js project. In a monorepo, run nextron add from apps/api.

Environment variables

Each module declares the variables it needs; nextron create writes all of them to .env.example, and nextron add prints the new ones. The most common:

| Module | Variables | | --- | --- | | database | DATABASE_URL | | auth (Better Auth) | BETTER_AUTH_SECRET, BETTER_AUTH_URL | | auth (Clerk) | CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | | auth (NextAuth) | AUTH_SECRET | | ai | AI_PROVIDER plus the key for your provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY) | | stripe | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | | polar | POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, optional POLAR_SERVER, POLAR_SUCCESS_URL | | inngest | INNGEST_EVENT_KEY, INNGEST_SIGNING_KEY | | express-database | MONGODB_URI, or SQLSERVER_SERVER / SQLSERVER_DATABASE / SQLSERVER_USER / SQLSERVER_PASSWORD | | express-auth | JWT_SECRET, optional JWT_EXPIRES_IN | | Expo app (mobile) | EXPO_PUBLIC_API_URL, and EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY with the Stripe module |

All variables are validated at boot through the generated src/env.ts (Next.js), src/config/env.ts (Express), or src/shared/env.ts (Expo) — a missing required variable fails fast with a clear message instead of a runtime crash deep in a request.

Generated structure

The exact files depend on the selected modules. A full application follows this shape:

customer-portal/
├── AGENTS.md
├── CLAUDE.md
├── nextron.config.ts
├── .env.example
├── package.json
└── src/
    ├── app/                  # Thin App Router entrypoints
    ├── components/ui/        # Shared UI primitives
    ├── env.ts                # Validated environment variables
    ├── modules/
    │   ├── auth/
    │   ├── database/
    │   ├── dashboard/
    │   ├── trpc/
    │   ├── ai/
    │   ├── stripe/
    │   └── inngest/
    └── shared/               # Cross-module utilities and types

Generated modules use these conventions:

• Page-level UI belongs in src/modules/<feature>/ui/views.
• Reusable feature UI belongs in src/modules/<feature>/ui/components.
• Server mutations belong in src/modules/<feature>/server/actions.ts.
• Read-only queries belong in src/modules/<feature>/server/queries.ts.
• Module-specific types belong in src/modules/<feature>/@types.
• Environment variables are accessed through src/env.ts.

Configuration

nextron.config.ts is generated at the project root and records the selected stack:

export default {
  name: 'customer-portal',
  version: '0.1.0',
  projectType: 'app',
  packageManager: 'pnpm',
  modules: ['database', 'auth', 'trpc', 'dashboard'],
  database: {
    orm: 'drizzle',
    type: 'postgresql',
    provider: 'neon',
  },
  auth: 'better-auth',
  trpc: true,
  dashboard: true,
};

Keep this file in version control. The add command uses it to select provider-specific templates, detect your package manager, and update the installed module list.

Failure and rollback behavior

• If project generation fails after creating a new target directory, Nextron removes that incomplete directory — no half-generated projects.
• If the target directory existed before the command started, Nextron never removes it.
• When adding a module, existing destination files are skipped with a warning. Review the output and integrate those files manually when you intentionally maintain a customized equivalent.
• If dependency installation fails, the generated files and the captured installer error are both surfaced so you can fix the cause (network, registry auth, disk) and re-run the install yourself.

Troubleshooting

No nextron.config.ts found

Run nextron add from the generated project root — the directory that contains nextron.config.ts.

Module is already in your project

The module is already recorded in nextron.config.ts. Inspect its files under src/modules instead of adding it again.

Module "X" is incompatible with "Y" / requires "Y"

The requested module's requirements conflict with, or are missing from, your current module set. The message names the exact modules involved; add the required module first or reconsider the combination.

Dashboard authentication error

Dashboard generation requires Better Auth, Clerk, or NextAuth. Create the application with authentication enabled.

Dependency installation failed

Generated files remain available. The error output from the package manager is printed; fix the underlying cause and run the selected package manager manually from the project directory:

pnpm install

Missing environment variables

Copy .env.example to .env.local, supply the required secrets, and restart the development server. The variables each module needs are listed in Environment variables.

Slow installs

pnpm and npm installs already run with --prefer-offline. If installs are still slow, warm the store once (pnpm store status) or check your registry configuration.

Develop the CLI in this repository

From the Nextron workspace root:

pnpm install
pnpm --filter @edwinfom/nextron build
node packages/cli/dist/index.mjs --help

Run the CLI directly against the workspace build:

node packages/cli/dist/index.mjs create example-app

Before submitting CLI changes, run:

pnpm turbo build typecheck test
pnpm test:dashboard-generation

The test suite includes a generation matrix that snapshots the full file tree for representative stacks and asserts that no unresolved {{placeholders}} remain in any generated file.

Versioning

See CHANGELOG.md for release notes. The CLI follows semantic versioning: patch releases never change the generated project layout or the command interface.

Documentation

The full developer documentation lives in apps/docs, including the getting-started guide, module reference, troubleshooting guide, and AI prompt builder.