Commands
Every command, what it does, and the same command in the four package managers people actually use.
The installation is tested with pnpm, which is what the lockfile in the folder is written for. Nothing stops
you using npm, Yarn or Bun: the scripts are ordinary package.json scripts, and the tabs below give each one in
the spelling you already type.
Pick one package manager and stay with it
The folder ships a pnpm-lock.yaml. A second lockfile from another manager is
a second opinion about versions, and the two will disagree eventually. If you
prefer npm or Yarn, delete the pnpm lockfile once and commit the one you
generate, rather than keeping both.
Install, run and build
pnpm install # the packages
pnpm configure # the guided walk over the nineteen names
pnpm dev # development server on http://localhost:3000
pnpm build # a production build
pnpm start # serve the production buildThe three gates
Run these before and after any change of your own. They are clean as shipped, and a gate that breaks is a gate that tells you what you broke while it is still one change old.
pnpm typecheck # TypeScript, no emit
pnpm lint # ESLint
pnpm test # Vitest, once
pnpm test:watch # Vitest, watching
pnpm format # Prettier over the TypeScript and TSX filesThe backend
Convex has a command line of its own, and it is the same one whichever package manager you used.
npx convex dev # create or connect, then watch and push to development
npx convex dev --once # push once and exit, for a script
npx convex deploy # push schema and functions to production
npx convex env set NAME value # one deployment variable
npx convex env set NAME value --prod
npx convex env list # which names the deployment has, never their values
npx convex env list --prod
npx convex run admin:bootstrap # create the first administrator
npx convex dashboard # open the dashboard for this project
npx convex logs # watch the deployment's log, where an action's failure shows upThe configuration walk
pnpm configure # every question
pnpm configure --only=app # only the seven the app reads
pnpm configure --only=deployment # only the twelve the deployment reads
pnpm configure --dry-run # say what it would write, write nothing
pnpm configure --yes # scripted: take the shipped answer
pnpm configure --file=.env.staging # write somewhere other than .env.local
pnpm configure --no-color # plain output, for a log
pnpm configure --help # the flags and the names`pnpm setup` is not this
pnpm has a setup command of its own and it will win the argument. The
script in this folder is configure. The Cloudflare scripts are
cf:-prefixed for the same reason: pnpm deploy is pnpm's own monorepo
deploy.
What each script is for
| Script | Runs | When |
|---|---|---|
dev | next dev | While you are working |
build | next build | Before start, and before a release |
start | next start | Serving a build. Reads what was built, not what is in the editor |
lint | eslint | Before a commit |
format | Prettier over **/*.{ts,tsx} | When the diffs start arguing about whitespace |
typecheck | tsc --noEmit | Before a commit, and after touching convex/ |
test | vitest run | Before a commit |
test:watch | vitest | While working on a rule in lib/ or convex/ |
configure | scripts/install.mjs, with Node's type stripping | First run, and when a key changes |
vendor | Copies the WebAssembly bundler into public/vendor | Automatically before dev and build, and after install |
skills | Writes lib/ai/skills-data.ts from the skills/ folder | Automatically before dev and build |
assets | Writes lib/assets.ts, the bytes the icon draws with | Automatically before dev and build |
cf:preview | opennextjs-cloudflare build then preview | To run the app in Cloudflare's local runtime on port 8787 |
| cf:deploy | opennextjs-cloudflare build then deploy --keep-vars | To put the app on Cloudflare Workers |
| cf:upload | opennextjs-cloudflare build then upload --keep-vars | To upload a version without promoting it, for gradual rollouts |
| cf:typegen | wrangler types | To regenerate cloudflare-env.d.ts after changing a binding |
| postinstall | The same vendoring | Automatically, after install |
The two generated files
lib/ai/skills-data.ts and lib/assets.ts are written by scripts, not by
hand. They exist because a runtime with no disk cannot read the skills/
folder or open a file in public/, and both happen while a page is being
answered. They are committed so a fresh clone typechecks, and regenerated
before every build, so editing the markdown or the image is still all you ever
do.
The things people look for, and where they are
| I want to | Command |
|---|---|
| Start over with the packages | Delete node_modules, then install again |
| Start over with the build | Delete .next, then pnpm build |
| Check which names are set, without values | npx convex env list, and Platform → Environment |
| See why a turn failed | npx convex logs |
| Check that the app is up before blaming code | System → Status & health in the panel |
| Find out who changed a setting | System → Audit log |
A blank page for a few seconds is not a fault
Next.js serves nothing until the first compile finishes, and the first compile after a restart is the whole app. In development that is a few seconds; on a production host it has already happened during the build.