Everything Nova, Explained
CLI commands, Architecture Presets, Vercel AI SDK streaming, plugin metadata, lifecycle maintenance, and deployment workflows.
Introduction
Getting Started
Nova is an extensible Next.js development toolkit and CLI for creating, generating, managing, and maintaining production-ready applications.
Run one command, answer interactive prompts or pass flags, and get a fully configured Next.js application with Next.js 16 Edge proxy architecture, authentication, internationalization, validation, API infrastructure, testing, UI frameworks, Infrastructure as Code (Kubernetes/Terraform), and optional plugins — instead of re-inventing infrastructure on every new codebase.
$ npx @darkalpha/nova my-appNo install required — always executes the latest Nova generator.
Or install Nova globally on your machine:
$ npm install -g @darkalpha/nova$ nova my-appQuick Start
$ npx @darkalpha/nova my-app --template saas$ cd my-app && cp .env.example .env$ npm installOnly needed if you skipped dependency install during setup.
$ npm run devOpen http://localhost:3000 — your app is running with locale-aware routing (/en, /fa), Next.js 16 Edge proxy routing (src/proxy.ts), working token rotation authentication, and a typed API client ready to point at your backend via API_BASE_URL.
>=18.18.0, and one of npm, pnpm, yarn, or bun installed on your machine.Introduction
Why Nova?
Most Next.js starters hand you a basic blank canvas and leave crucial architectural decisions to the developer: How should auth token refresh work? Where do validation schemas live? How is the API client structured? Should translations be typed? Nova answers these questions up front so you don't have to 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.
Batteries Included
Authentication, token rotation, internationalization, form validation, databases, storage, payments, state management, and Docker support.
Composable Plugins (35+)
Choose only what you need. Layer features onto existing codebases incrementally with nova add.
Infrastructure & Security Engine
Kubernetes manifests, Terraform HCL, CIS security scanner (SEC-001..SEC-010), and automated drift detection via nova infra.
Live Package Version Resolution
Resolves live compatible package versions from npm registry with strategies (latest, compatible, exact).
Introduction
Key Features
Nova provides a flexible, battle-tested foundation for modern Next.js applications:
- Next.js 16 App Router & Edge proxy (
src/proxy.ts, Server Components, Streaming SSR) - Infrastructure as Code & K8s (
nova infra: Kubernetes, Terraform, CIS security scanner, drift detection) - 9 Official Starter Templates (Minimal, SaaS, Admin Dashboard, E-commerce, Blog CMS, AI, Realtime SSE, API, Mobile)
- Vercel AI SDK integration (OpenAI, Anthropic Claude, Ollama local LLMs)
- Multi-Driver File Storage (Local filesystem, AWS S3, Supabase Storage) with reactive FileUpload UI
- Real-time Events & Server-Sent Events (SSE) with NotificationCenter UI
- Payments & Billing Abstraction (Stripe, LemonSqueezy, Paddle, Mock)
- Live npm Package Resolver & Outdated Inspector (
nova packages) - Automated Project Migration Engine & Self-Healing (
nova repair) - Database integrations: Drizzle ORM (SQL-first) or Prisma ORM
- Authentication: Custom HTTP-only token rotation or Better Auth
- Type-safe APIs: tRPC, GraphQL Yoga, and OpenAPI client codegen
- 8 UI Frameworks: shadcn/ui, MUI, Chakra, Ant Design, Mantine, HeroUI, DaisyUI, Headless UI
- Testing: Vitest, Playwright E2E, Cypress, Storybook 8, and automated Husky git hooks
- Cloud Deployment Hub: Vercel, Cloudflare Pages, Railway, Render, AWS, Docker
Introduction
What's Included in Base Projects
Every generated project includes a production-oriented foundation:
Next.js 16 Edge Proxy Architecture (`src/proxy.ts`)
Replaces legacy middleware.ts with Next.js 16 native src/proxy.ts for edge routing, header mutations, and authentication checks.
Internationalization & RTL
Powered by next-intl with locale-prefixed routing (/en, /fa), typed message dictionaries, and native RTL layout support.
Authentication & Token Rotation
Includes access token & refresh token rotation in HTTP-only secure cookies with concurrent refresh request coalescing to prevent race conditions.
Form Handling & Validation
React Hook Form combined with shared Zod validation schemas across client components and server actions.
Type-Safe API Infrastructure
Robust fetch client wrapper with automatic retry policies, timeouts, request/response interceptors, and error handling.
CLI & Workflow
CLI Reference & Usage
Nova supports complete project generation, architecture presets, templates, package resolution, infrastructure management, environment management, and self-healing lifecycle maintenance.
nova [create] [project-name] [--template <template>] [--preset <preset>] [--ui <ui>] [--pm <pm>] [-y]
nova templates [--json]
nova template info <name>
nova presets
nova packages [--outdated] [--json]
nova infra <init|plan|apply|destroy|scan|diff|drift|scale> [options]
nova search <query>
nova plugins [subcommand|feature] [options]
nova plugin <create|validate|test|build|info> [options]
nova env [check|example] [options]
nova add <feature...> [options]
nova remove <plugin...> [--path <dir>] [--force] [--dry-run]
nova init | info | doctor | validate | clean | diff [--path <dir>] [options]
nova status [--path <dir>] [--json]
nova upgrade [--path <dir>] [--dry-run] [plugin...]
nova repair [--path <dir>] [--dry-run]
nova deploy [provider] [--path <dir>] [--force] [--dry-run] [--list]CLI Options & Flags
| Flag | Description |
|---|---|
-h, --help | Show help message |
-v, --version | Print installed Nova version |
-t, --template <name> | Official template: minimal, saas, admin, ecommerce, blog, ai, realtime, api, react-native |
--preset <name> | Architecture preset: minimal, saas, admin, ecommerce, blog, ai, realtime, api |
--ui <library> | UI Library: shadcn, mui, chakra, ant, mantine, hero, daisy, headless |
--pm, --package-manager | Package manager: pnpm, npm, yarn, bun |
-y, --yes | Non-interactive mode (apply defaults automatically) |
--dry-run | Preview planned changes without writing or modifying files |
--fix | Automatically repair deterministic configuration, environment, and migration drift |
--json | Print structured JSON output for scriptability and CI pipelines |
CLI & Workflow
Architecture Presets & Starter Templates
Nova provides 9 curated starter templates and architecture presets so you can launch complete production stacks in seconds:
Official Starter Templates (nova templates)
| Template | Architecture Focus | Command |
|---|---|---|
| Minimal Next.js | Next.js 16 proxy.ts + TypeScript + Tailwind CSS + shadcn | nova create my-app --template minimal |
| SaaS Application | Drizzle ORM + Better Auth + React Email + Storage + Payments + Sentry | nova create my-saas --template saas |
| Admin Dashboard | Better Auth + Drizzle + TanStack Table + Recharts + Zustand | nova create my-admin --template admin |
| E-commerce Platform | Products Schema + Cart State + Orders + Payments + Uploads | nova create my-store --template ecommerce |
| Blog & CMS | Tiptap Editor + Drizzle ORM + TanStack Table + Media Storage | nova create my-blog --template blog |
| AI Application | Vercel AI SDK + Multi-model Streaming + Storage Uploads + Chat UI | nova create my-ai --template ai |
| Real-time Application | SSE Streaming + Notification Center + Redis + Zustand State | nova create my-live-app --template realtime |
| Microservice API | Headless Next.js + tRPC + OpenAPI + Docker + Health Probes | nova create my-api --template api |
| Expo Mobile App | Expo SDK 52 + React Native 0.76 + TypeScript | nova create my-mobile --template react-native |
Official Presets (nova presets)
| Preset | Focus | Included Plugins | Command |
|---|---|---|---|
| Minimal Next.js | Lean Starter | vitest, husky | nova create my-app --preset minimal |
| Subscription SaaS | SaaS Platform | drizzle, betterAuth, reactEmail, mailpit, storage, payments, tanstackQuery, sentry, vitest, playwright, husky | nova create my-saas --preset saas |
| Enterprise Admin & Dashboard | Admin & Analytics | betterAuth, drizzle, tanstackTable, recharts, tanstackQuery, zustand, vitest, playwright, husky | nova create my-admin --preset admin |
| E-commerce Platform | E-Commerce | betterAuth, drizzle, zustand, tanstackTable, payments, storage, vitest, playwright, husky | nova create my-store --preset ecommerce |
| Blog & Content Publishing | Content & CMS | betterAuth, drizzle, tiptap, tanstackTable, storage, tanstackQuery, vitest, husky | nova create my-blog --preset blog |
| Conversational AI Platform | Generative AI | ai, openai, betterAuth, storage, zustand, tanstackQuery, vitest, husky | nova create my-ai --preset ai |
| Real-time & Live Streaming | Real-time Live | realtime, betterAuth, drizzle, redis, zustand, tanstackQuery, vitest, husky | nova create my-live-app --preset realtime |
| Microservice API Backend | Headless API | trpc, openapi, docker, health, vitest, husky | nova create my-api-service --preset api |
CLI & Workflow
AI & LLM Ecosystem
Nova features first-class native support for Generative AI applications powered by the Vercel AI SDK:
ai (Vercel AI SDK Core)
Streaming edge route handlers (src/app/api/chat/route.ts) and reactive chat components.
nova add aiopenai Provider
@ai-sdk/openai integration with GPT-4o, GPT-4o-mini, and o1 models.
nova add ai openaianthropic Provider
@ai-sdk/anthropic integration for Claude 3.5 Sonnet and Haiku.
nova add ai anthropicollama Local Provider
ollama-ai-provider for zero-cost, private local LLM development.
nova add ai ollamaCLI & Workflow
Dynamic Package Version Resolution (`nova packages`)
Nova resolves latest compatible package versions from the npm registry at generation time instead of hardcoding stale versions in boilerplate files.
$ nova packagesInspect all Nova-managed packages and version ranges
$ nova packages --outdatedShow only packages that have compatible updates available
$ nova packages --jsonOutput machine-readable package manifest data
Resolution Strategies
- compatible (default): Resolves the latest version within the validated major range.
- latest: Fetches the absolute latest published package version from npm.
- exact: Pins exact version strings without semver caret/tilde ranges.
- Offline Fallback: Automatically falls back to verified static versions if offline or npm registry is unreachable.
CLI & Workflow
Adding Features to Existing Projects (`nova add`)
nova add performs safe, transactional feature additions into existing projects without regenerating from scratch.
$ nova add storage realtime paymentsLayer uploads, live streaming, and billing in one step
$ nova add trpc --dry-runPreview planned changes with dry-run
$ nova add sentry --forceRe-copy template files if needed
Guarantees & Safety Mechanisms
- Validate Before Write: Validates requested plugins against currently installed plugins (e.g. rejecting Drizzle if Prisma is already active) before modifying files.
- Atomic Rollback: If an error occurs during template rendering or dependency patching, all changes are automatically rolled back.
- Dry-Run Preview: Pass
--dry-runto preview planned file additions, modifications, package.json dependencies, and manifest changes. - Non-Destructive Script Merge: Merges scripts into package.json without overwriting scripts you have already customized.
CLI & Workflow
Project Maintenance & Diagnostics
Nova provides a dedicated suite of maintenance commands to monitor project health and fix configuration drift:
| Command | Purpose & Diagnostic Scope |
|---|---|
nova status [--json] | Show project identity, structure, active plugins, and health summary. |
nova doctor [--fix] | Comprehensive environment (Node, PM, OS), lockfile, dependencies, and plugin compatibility diagnostics with transactional auto-repair. |
nova validate | Run plugin validations against current project state. |
nova info | Detailed project architecture, router layout, cloud deployment statuses, and available scripts. |
nova remove <plugin...> | Safely uninstalls plugin metadata, package dependencies, and scripts without deleting user-modified code. |
nova upgrade [--dry-run] | Reconcile tracked plugin dependency declarations with current manifests without clobbering source files. |
nova repair [--dry-run] | Auto-repair deterministic metadata, .env.example contributions, missing scripts, and apply project migrations. |
nova diff [plugin] | Report categorized drift ([SAFE TO REPAIR], [MANUAL REVIEW REQUIRED], [INFORMATIONAL]). |
nova clean [--dry-run] | Remove build artifacts and caches (.next, .turbo, node_modules/.cache, dist). |
CLI & Workflow
Project Migrations & Self-Healing
Nova includes an automated project migration runner and manifest reconstruction engine to ensure older projects seamlessly adopt latest framework standards.
$ nova repairRun self-healing checks and apply pending project migrations
$ nova repair --dry-runPreview planned migrations without writing changes
Built-In Project Migrations
| Migration ID | Scope & Description |
|---|---|
proxy-migration | Migrates legacy middleware.ts to Next.js 16 native proxy.ts edge architecture. |
schema-v1-migration | Normalizes project manifest to schemaVersion 1 with authoritative .nova/project.json. |
env-template-hygiene | Ensures all active plugin environment variables are documented in .env.example. |
Manifest Reconstruction
If .nova/project.json is missing or corrupted, Nova automatically infers installed plugins, package manager, and UI library from package.json to reconstruct the manifest losslessly.
CLI & Workflow
Environment Management (`nova env`)
Nova tracks environment variables declared by installed plugins and provides validation without exposing secret values:
$ nova envCheck status of required and optional environment variables
$ nova env checkValidate required variables in CI pipelines (exits with code 1 if missing)
$ nova env exampleSynchronize .env.example with newly added plugin requirements
CLI & Workflow
Project State Model (`.nova/project.json`)
Nova stores its authoritative project state under .nova/project.json (and keeps .nova.json in sync for backward compatibility). Infrastructure state is tracked separately under .nova/infrastructure.json.
{
"$schema": "https://nova.dev/schema/project.json",
"version": 1,
"schemaVersion": 1,
"name": "my-saas",
"novaVersion": "0.2.5",
"createdAt": "2026-08-20T00:00:00.000Z",
"updatedAt": "2026-08-20T00:00:00.000Z",
"packageManager": "pnpm",
"uiLibrary": "shadcn",
"projectType": "nextjs",
"template": "saas",
"preset": "saas",
"plugins": ["drizzle", "betterAuth", "storage", "payments", "reactEmail", "sentry"],
"pluginVersions": {
"drizzle": "1.0.0",
"betterAuth": "1.0.0",
"storage": "1.0.0",
"payments": "1.0.0"
},
"customMetadata": {}
}Ecosystem & Plugins
Plugin Registry & Discovery
Discover and inspect plugins across built-in, verified, and community sources:
$ nova search databaseSearch for plugins by keyword or category
$ nova plugins search authSearch within the plugins subcommand
$ nova plugins tree trpcInspect plugin dependency tree
$ nova plugins conflicts drizzleCheck plugin conflict rules
Plugin Development SDK
Nova provides a complete SDK to build, validate, test, and distribute custom plugins:
$ nova plugin create my-custom-plugin --category authentication$ nova plugin validate$ nova plugin test$ nova plugin buildEcosystem & Plugins
Storage, Real-time & Payments
Nova introduces turnkey feature abstractions for production workflows:
File Storage & Uploads
Multi-driver storage (Local filesystem, AWS S3, Supabase Storage) with upload API routes and reactive FileUpload component.
nova add storageReal-time Events (SSE)
Server-Sent Events streaming with presence tracking and a ready-to-use NotificationCenter component.
nova add realtimePayments & Billing
Modular billing abstraction (Stripe, LemonSqueezy, Paddle, Mock) with checkout sessions, pricing tables, and webhook routing.
nova add paymentsEcosystem & Plugins
Plugin Catalog & Conflict Matrix
Every plugin can be selected at initial setup or added later with nova add:
| Category | Available Plugins |
|---|---|
| AI & LLM | Vercel AI SDK, OpenAI Provider, Anthropic Claude, Ollama Local LLM |
| Data and Backend | Drizzle ORM, Prisma ORM, Supabase, Better Auth, Redis, Strapi CMS, Storage & Uploads, OpenAPI |
| APIs, Fetching & State | tRPC, GraphQL Yoga, Real-time Events (SSE), Payments & Billing, TanStack Query, TanStack Table, Zustand, MSW |
| Testing | Vitest, Playwright, Cypress, Storybook 8, Husky + lint-staged Git Hooks |
| Content & Communication | React Email, Mailpit SMTP, Tiptap Rich Text |
| Infrastructure & Operations | Kubernetes Manifests, Terraform HCL, Docker, Cloud Deploy (Vercel, Cloudflare, Railway, Render, AWS), Sentry, Health Probes, Security Headers |
| Design and UX | Design System Primitives, Framer Motion Animations, Recharts Visualization |
Known Plugin Conflicts
DATABASE_URL-backed schema definitions and contribute colliding db:* scripts — select exactly one ORM per project.Ecosystem & Plugins
UI Frameworks
Nova supports 8 distinct UI library approaches:
| Select Flag | Library | Architecture Notes |
|---|---|---|
shadcn | shadcn/ui (Default) | Tailwind CSS v4, Radix UI primitives, source-based accessible components |
mui | Material UI | Google Material Design components, App Router cache provider, theme config |
chakra | Chakra UI | ChakraProvider, theme configuration, composable style props |
ant | Ant Design | Ant Design enterprise components, ConfigProvider, theme support |
mantine | Mantine | MantineProvider, theme configuration, 100+ components & hooks |
hero | HeroUI | HeroUI provider, modern component primitives, theme integration |
daisy | DaisyUI | Tailwind plugin, theme presets, zero JavaScript runtime overhead |
headless | Headless UI | Headless UI primitives, Tailwind integration, Heroicons |
Ecosystem & Plugins
Project Architecture & Folder Layout
Generated applications follow a clean, feature-first modular architecture with Next.js 16 Edge proxy routing:
src/
├── proxy.ts # Next.js 16 Edge proxy (replaces legacy middleware.ts)
├── app/ # App Router routes, grouped under [locale]
├── actions/ # Cross-cutting Server Actions not tied to one feature
├── components/
│ ├── ui/ # Primitive components (button, input, card...)
│ ├── common/ # Small generic UI (spinner, FileUpload, NotificationCenter)
│ ├── layout/ # Header, footer, theme/locale switchers
│ ├── forms/ # Form wrapper, field, error components
│ └── providers/ # Client provider composition root
├── features/ # Feature-first domain modules (auth, billing, ai, storage)
│ └── <feature>/
│ ├── components/
│ ├── hooks/
│ ├── actions/
│ ├── schemas/
│ └── types/
├── hooks/ # App-wide reusable hooks
├── lib/
│ ├── api/ # Type-safe fetch client + interceptors
│ ├── auth/ # Token rotation & session helpers
│ ├── db/ # Drizzle client & schema (or prisma/)
│ ├── storage/ # Multi-driver storage abstraction
│ ├── realtime/ # Server-Sent Events client & helpers
│ ├── payments/ # Payments & checkout abstraction
│ ├── validations/ # Shared Zod validation schemas
│ └── cache/ # Cache tag registry
├── services/ # Business operations calling lib/api
├── utils/ # Pure utility functions
├── config/ # Site config & validated environment variables
├── messages/ # next-intl translation JSON files (en, fa)
└── i18n/ # next-intl routing & request configurationArchitecture Rules of Thumb
features/owns anything specific to one product area — start here for new features.lib/owns cross-cutting infrastructure (HTTP, auth, database, storage, payments).proxy.tsowns Edge header mutations, internationalization redirects, and route guarding.services/is the single layer allowed to calllib/apidirectly for business data.
Operations & IaC
Infrastructure as Code & Kubernetes (`nova infra`)
Nova features a pluggable Infrastructure as Code engine supporting Kubernetes, Terraform, Docker, and Docker Compose out of the box with automated security audits and drift management.
$ nova infra init kubernetes --profile productionGenerates hardened K8s manifests (Deployment, Service, HPA, Ingress, TLS)
$ nova infra scanAudits manifests against 10 CIS Kubernetes security benchmarks (SEC-001..SEC-010)
$ nova infra diffDetects infrastructure configuration drift against desired state
$ nova infra scale --replicas 5Scales application deployment replicas on the fly
Operational Profiles
| Profile | Target Environment | Scaffolded Infrastructure Capabilities |
|---|---|---|
minimal | Development / Staging | Single container deployment & local Docker Compose stack. |
standard | Pre-production | Kubernetes deployment with ClusterIP service and CPU/Memory limits. |
production | Production | Non-root securityContext, HPA auto-scaling, TLS Ingress, readiness/liveness probes. |
high-availability | Multi-region Enterprise | PodDisruptionBudgets, anti-affinity rules, multi-zone replica scheduling & Terraform ECR/AppRunner. |
Operations & IaC
Cloud Deployment (`nova deploy`)
Nova provides first-class cloud deployment support through the nova deploy command, generating tailored configurations, automated CI/CD workflows, Dockerfiles, and production guides:
$ nova deploy --listList supported cloud deployment providers
$ nova deploy vercelGenerates vercel.json & GitHub Actions workflow
$ nova deploy cloudflareGenerates wrangler.toml & Pages workflow
$ nova deploy railwayGenerates railway.json with Nixpacks config
$ nova deploy dockerGenerates multi-stage Dockerfile.prod & compose
Operations & IaC
Generator Internals
Nova's generator is built around strict architectural principles for safety and predictability:
| Module | Responsibility |
|---|---|
context.ts | Builds a single, frozen GeneratorContext threaded through generation. |
infrastructure/*.ts | InfrastructureProviderRegistry engine for Kubernetes, Terraform, Docker. |
resolver/index.ts | Dynamic npm PackageResolver querying live registry versions. |
migrations/index.ts | runProjectMigrations engine with self-healing transaction tracking. |
logger.ts | Structured logger with CI-aware minimum log level. |
errors.ts | Typed error classes with actionable recovery messages. |
pluginMetadata.ts | Declarative metadata: requires, conflicts, supportedUI. |
validators.ts | validatePluginSelection() checks selection before writing files. |
operations.ts | OperationPlan data structures with automatic rollbackTargetDir() on failure. |
hooks.ts | HookRegistry supporting lifecycle hooks (beforeGenerate, afterUpgrade, etc.). |
Operations & IaC
Authoring a New Plugin
To contribute a new plugin to Nova:
- Create the template directory under
templates/addons/<plugin-name> - Add the feature key in
src/types.ts - Register in
src/addonRegistry.ts - Declare dependencies and scripts once in
src/featureContributions.ts - Add metadata and constraint rules in
src/generator/pluginMetadata.ts - Author rich contributions (env, patches, docs) in
src/plugin/nativePlugins/<name>.ts - Run
npm run verify:manifest-syncand smoke tests to ensure consistency.
Operations & IaC
FAQ & Troubleshooting
Common Troubleshooting Scenarios
Directory "my-app" already exists and is not empty.
Nova refuses to overwrite existing directories to prevent data loss. Choose another name or empty the directory.
Plugin conflict error (e.g. Prisma + Drizzle).
Prisma and Drizzle cannot coexist. Run nova plugins conflicts <name> to inspect conflict rules.
Corrupted or missing .nova/project.json manifest.
Run nova repair to automatically reconstruct your project manifest from package.json.
Operations & IaC
Roadmap & Contributing
Contributions are welcome! Before submitting a pull request:
$ npm install$ npm run typecheck && npm run verify:manifest-sync$ npm run build && node scripts/smoke-test.mjsFor full release history and changes, check the CHANGELOG.md on GitHub.