Inspected version: 0.3.3 (package manifest) · Part of the veap-repo monorepo (packages/create-veap).

create-veap scaffolds a new Veap application. It does not duplicate Next.js boilerplate: it runs the official create-next-app, then applies a Veap "overlay" and mutates the generated project.

**Version note:** the manifest records `0.3.3`, while the CLI prints `0.4.0` in `src/index.ts`. Verify the installed binary's declared version before relying on a specific number.

Entry points #

bin.create-veap → ./bin/veap.js (the executable).
. → dist/main.js, which re-exports initProject and the PackageManager type.

CLI usage #

bash

# Interactive (prompts for name, Docker)
npx create-veap

# Explicit name
npx create-veap my-veap-app

# Scoped name (folder becomes the base name, package.json keeps the scope)
npx create-veap @my-scope/my-app

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

Option	Effect
`[name]`	Project name; when omitted the CLI prompts (and resolves to the default on a non-TTY).
`--docker`	Also generate Docker files. When omitted on a TTY the CLI asks.
`--skip-install`	Skip the final dependency install.
`--pm <manager>`	Use `pnpm`, `npm`, `yarn` or `bun`.
`--pnpm`, `--bun`, `--npm`, `--yarn`	Boolean shortcuts for the same choice.
`--help`, `--version`	Standard CLI output.

Programmatic API #

import { initProject } from "create-veap";

await initProject("my-app", { pm: "pnpm", docker: false, skipInstall: true });

What the scaffolder does #

Scaffolds the Next.js shell with create-next-app using explicit, non-interactive flags (--ts --tailwind --app --eslint --react-compiler --import-alias "@/*" --skip-install). If the package-manager-specific runner fails (for example a network/IPv6 timeout), it falls back to npx.
Clears the generated app/ directory and applies the Veap overlay. The overlay owns the whole app/ tree because a leftover CNA page route would collide with Veap's optional catch-all route ("same specificity as an optional catch-all route").
Mutates the project: merges the Veap dependency manifest into package.json, overrides @types/node and adds engines.node >= 22, writes a starter .env (with a fresh random 16-byte base64 ENCRYPTION_KEY) and appends Veap entries to .gitignore.
Creates public/, storage/ and plugins/ directories.
Applies package-manager specifics (see below).
Optionally generates Docker files (Dockerfile, compose.yml, .dockerignore).
Runs a single dependency install (unless --skip-install).

Package-manager resolution #

resolvePackageManager() resolves in this order:

Boolean flags (--pnpm, --bun, --npm, --yarn).
--pm <manager>.
Auto-detection of the environment running the CLI (npm_config_user_agent, process.versions.bun, npm_execpath).
Auto-detection from the current directory: packageManager field, then lockfiles, then the framework default (pnpm).

Per-manager project setup: pnpm/yarn pin packageManager (corepack); pnpm writes pnpm-workspace.yaml (with plugins/*) only when missing; yarn adds .yarnrc.yml with nodeLinker: node-modules; npm/bun remove packageManager and switch to the workspaces field.

Project-name rules #

parseProjectName() follows npm package-name rules: lowercase only, max 214 characters, scoped names (@scope/name) supported, reserved scopes/names rejected (veap, next, react, vercel, npm, node, typescript, types and the corresponding bare names), and a filesystem collision check against the target folder.

Generated `.env`#

typescript

ENCRYPTION_KEY="<random 16-byte base64>"
DATABASE_URL="sqlite:./storage/veap.sqlite"
MAIL_TRANSPORT=smtp

Caveats #

The dependency manifest injects @veap/framework and @veap/ui (latest). @veap/framework is the monolithic-era package name; this monorepo publishes the split packages (@veap/kernel, @veap/database, …). Confirm which packages create-veap actually installs matches the package set you intend to use.
The overlay files live in stubs/ and are copied verbatim (with {{name}} substitution); they are not compiled from src/.