Everything Nova generates, explained

Nova is an extensible Next.js CLI that scaffolds a production-ready App Router application — authentication, a typed API layer, internationalization, forms, testing, and an optional plugin system — instead of leaving those decisions to you on every new project.

Or install it globally and use the short form:

Quick start

Open http://localhost:3000 — the app runs with locale-aware routing (/en, /fa), a working token-rotation auth flow, and a typed API client pointed at API_BASE_URL.

Run nova with no arguments for a fully interactive setup — it prompts for the project name, package manager, UI library, and plugins, and validates the combination before writing a single file.

Most starters hand you a blank App Router project and leave the architectural decisions to you: how token refresh works, where validation schemas live, how the API client is structured. Nova answers those questions up front so you don't relitigate them on every project — and stays a plain, ownable Next.js codebase once it's generated, with no runtime dependency on the nova package.

• Composable plugins — pick only what you need, and layer more on later with nova add.
• Swappable technologies — eight UI libraries, multiple data and auth layers, no forced defaults.
• Documented architecture — generated projects ship their own docs/ folder and module-local READMEs.
• Predictable generation — plugin selections are validated before any file is written, and a failed generation rolls back cleanly instead of leaving a half-built project on disk.

Nova has three entrypoints: generating a new project, adding features to an existing one, and inspecting plugins.

nova [project-name] [options]
nova add <feature...> [options]
nova plugins [feature]

Examples

Project names may only contain lowercase letters, numbers, dashes, and underscores (^[a-z0-9-_]+$). Invalid names are rejected before any files are written.

Running in CI

With CIset in the environment, Nova skips the "install dependencies now?" prompt and switches its logger to a quieter, CI-friendly level:

Copies an addon's files into a project that already exists and merges its dependencies and scripts into that project's package.json — the incremental counterpart to selecting a plugin at scaffold time.

Omit the feature list for an interactive multiselect with the same options as initial generation.

What it does

1. Reads the target's package.json — the directory must already be a Node/Next.js project.
2. Detects whether the project uses a src/ directory and remaps addon files accordingly.
3. Creates whatever intermediate folders are needed.
4. Merges dependencies, devDependencies, and scripts from src/featureContributions.ts — the same source full generation reads, so a feature installs identically either way.
5. Skips files that already exist, so re-running is safe — pass --force to overwrite.

Inspect what a plugin does before adding it, without reading source files.

Reads from the same metadata (src/generator/pluginMetadata.ts) and package contribution data (src/featureContributions.ts) that generation itself uses, so the output can never drift from what nova <name> or nova add actually do.

Every plugin can be selected at generation time, added later with nova add, and inspected any time with nova plugins.

Each plugin is a self-contained overlay under templates/addons/<name> — enabling it copies its files on top of the base template and wires in dependencies, scripts, and environment variables automatically. Declarative metadata (requires/conflicts/supportedUI) is validated against your full selection before any files are written.

Nova supports eight UI approaches, wired with theming, dark mode, and a demo dashboard.

Generated applications follow a feature-first architecture.

src/
├── app/            # App Router routes, grouped under [locale]
├── components/
│   ├── ui/           # shadcn/ui-style primitives
│   ├── layout/        # Header, footer, switchers
│   ├── forms/          # Form wrapper, field, error components
│   └── providers/       # Client-side provider wrappers
├── features/         # Feature-first modules (auth, dashboard...)
│   └── <feature>/
│       ├── components/
│       ├── hooks/
│       ├── actions/
│       ├── schemas/
│       └── types/
├── lib/
│   ├── api/            # Type-safe fetch client + interceptors
│   ├── auth/            # Token rotation, session helpers
│   ├── prisma/           # Prisma client singleton
│   ├── validations/       # Shared zod schemas
│   └── cache/              # Cache tag registry
├── services/         # Business-shaped calls, built on lib/api
├── utils/            # Pure utility functions
├── i18n/             # next-intl routing/navigation config
└── messages/
    ├── en/
    └── fa/

Rule of thumb

• features/ owns anything specific to one product area — start here for new work.
• lib/ owns cross-cutting infrastructure: HTTP, auth, database.
• components/ owns reusable UI with no business logic.
• services/ is the only place allowed to call lib/api directly for business data — features call services, not the API layer, so the transport can change independently.

Generated projects include a .env.example covering every variable the scaffold understands, grouped by category:

• App — public URL/name, safe to expose via NEXT_PUBLIC_*
• Database — DATABASE_URL, used by Prisma if enabled
• Authentication — token secrets/TTLs, or Better Auth secrets
• External APIs — base URL/timeout for src/lib/api
• Sentry — DSNs and trace sample rates, when enabled

Vercel (recommended default)

Push to a connected git repository — Vercel auto-detects Next.js. Set the environment variables from .env.example in the project settings.

Docker (if selected during generation)

The generated Dockerfile uses a multi-stage build (deps → build → runtime) and Next.js output: "standalone" for a minimal production image. Every variable in .env.example must be set in production.

Common errors

Before submitting changes:

When contributing a new plugin or UI integration:

• Keep the plugin isolated and avoid unnecessary dependencies.
• Declare its package.json footprint once, in src/featureContributions.ts.
• Declare metadata and constraints in src/generator/pluginMetadata.ts.
• Prefer a new contribution in src/generator/patchers/ over a new if branch in generator.ts.
• Add documentation and smoke-test coverage.
• Run npm run verify:manifest-sync before opening a PR that touches package.json contributions.