Create a project with the CLI

create-veap scaffolds a new Veap application on top of Next.js. It delegates the Next.js boilerplate to the official create-next-app, then layers Veap files and configuration on the result.

Run it#

# Interactive
npx create-veap

# Named project, choose the package manager, skip the install
npx create-veap my-app --pm pnpm --skip-install

# Also generate Docker files
npx create-veap my-app --docker

# Scoped npm name (the folder uses the base name)
npx create-veap @my-scope/my-app

With bun or pnpm you can use their create runners instead:

bun create veap
pnpm create veap

What it produces#

1. A Next.js App Router project created by create-next-app (TypeScript, Tailwind, ESLint, React Compiler, @/* import alias).
2. A Veap overlay over the app/ tree (layout, optional catch-all route, API pipeline, storage route, bootstrap, next.config).
3. package.json mutations: Veap dependencies injected, @types/node overridden and engines.node >= 22 added.
4. A starter .env with a random ENCRYPTION_KEY, a SQLite DATABASE_URL and MAIL_TRANSPORT=smtp.
5. public/, storage/ and plugins/ directories.
6. Package-manager configuration (packageManager pin for pnpm/yarn, pnpm-workspace.yaml, .yarnrc.yml, or the workspaces field).
7. Optional Docker files, and a single dependency install.

Choose a package manager#

Resolution order: explicit boolean flags (--pnpm, --bun, --npm, --yarn) → --pm <name> → the environment running the CLI → the current directory (packageManager field, then lockfiles) → the default (pnpm). The CLI never hangs: on a non-interactive terminal every prompt resolves to its default.

Encryption key#

The generated .env contains a random 16-byte base64 ENCRYPTION_KEY used for AES encryption at rest. Applications built on the Veap runtime fail fast at boot if the key is missing or does not decode to 16/24/32 bytes. Regenerate it with openssl rand -base64 16 and never commit .env.

After scaffolding#

cd my-app
npm run dev

Then open the app and follow Create your first application and Next.js integration to build the composition root and connect providers.

Caveats#

• The generated dependency manifest injects @veap/framework and @veap/ui. @veap/framework is the monolithic-era name; this monorepo publishes separate packages. Verify that what the scaffolder installs matches the package set you intend to use, and adjust package.json if needed.
• The overlay files are copied verbatim from the package's stubs/ with {{name}} substitution; review generated files before committing.