Getting started

Prerequisites. A Kubernetes cluster with Knative Serving installed (don't have one? Your first cluster gets you a laptop cluster in minutes), Next.js 16.x, and a container registry. An object-storage bucket (gcs, s3, minio, or azure) is optional — start without one (your app serves its static files from its own image, like next start) and add it later for CDN offload. See Starting without object storage.

Always run the CLI as npx @getknext/core ... (or a locally installed knext, after npm i @getknext/core), as shown throughout this page. Never run bare npx knext on its own — the unscoped name knext on the public npm registry belongs to an unrelated package, so outside a project where @getknext/core is already installed, npx knext downloads and runs someone else's code instead of this CLI.

The CLI command was renamed from kn-next to knext. kn-next still works as a deprecated alias — same command, same flags — and it does not print the reminder on every invocation shape, so do not assume its absence means you already switched. A locally installed kn-next run directly (on your PATH, or from an npm run script naming it) prints a one-line reminder to switch; npx/npm exec (including npx @getknext/core ...) does NOT, since npm's own bin-resolution for that path is ambiguous between the two names; pnpm's dlx/exec and Windows .cmd/.ps1 shims don't either. kn-next will be removed in 2.0. Update scripts/CI to knext before then.

What each package exports. @getknext/core exports the KnativeNextConfig type from its root, the adapter from /adapter (what adapterPath points at), the ISR cache handler from /adapters/cache-handler, and the pure config validator (validateConfig, ConfigValidationError) from /validate. @getknext/lib exports getDbPool() / getDbPoolRO() / closeDbPool(), getMinioClient(), getCerbosClient(), checkDeepHealth() / checkShallowHealth(), the logger, and the request-correlation helpers — all also re-exported from the package root. @getknext/db exports getDb() / getDbRO() plus the whole of drizzle-orm.

Starting a new app instead? npx @getknext/core create my-app scaffolds one with all of the steps below already done. On a terminal it asks five questions — runtime (bun or node), builder (turbopack, webpack, or vinext), cache (none or redis), object storage (none, gcs, s3, minio, or azure), and React Compiler (on by default; --no-react-compiler leaves it off). Enter takes the default each time. Every question has a flag, and --yes skips them all, so CI never waits:

npx @getknext/core create my-app --runtime node --cache redis --yes

See knext create for what each answer writes.

You do not need to run the npm i above first: npx @getknext/core create my-app works from any directory. If you did install into a parent directory, that is fine too — the scaffolded next.config.ts pins Next.js's file-tracing root to the app itself (outputFileTracingRoot), so a package-lock.json in the parent does not move the root.

Next.js 16.0.x–16.1.x: the option lives under experimental on those versions (experimental: { adapterPath: '@getknext/core/adapter' }). Next.js 16.2+ auto-migrates the old experimental key with a warning; 16.0.x does not recognize the top-level form.

An app below a lockfile. Next.js picks its file-tracing root by walking up to the outermost lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock) or pnpm-workspace.yaml. When that is a directory above your app, it writes the standalone server to .next/standalone/<your-app>/server.js instead of .next/standalone/server.js, and knext build stops with an error that names the inferred root and the lockfile responsible. output: 'standalone' is not the problem. Fix it by pinning the root in next.config.ts:

const config: NextConfig = {
  adapterPath: '@getknext/core/adapter',
  output: 'standalone',
  // This app's own directory.
  outputFileTracingRoot: import.meta.dirname,
  turbopack: { root: import.meta.dirname },
};

or remove the lockfile you do not need. knext deploy reads outputFileTracingRoot too, to choose the directory it sends to docker build.

A workspace monorepo is the one case where a root above the app is what you want. If the app shares packages with a root above it, set that root on purpose in both keys and knext packages the nested layout; see Deploy from a workspace monorepo. A root that was only inferred from a parent lockfile is never treated that way.

If you configure storage, its provider is validated against gcs | s3 | minio | azure. Each shells out to that cloud's CLI (gsutil / aws / mc / az), which must be installed and authenticated in your build environment. See Multi-cloud deploy.

The operator is the source of truth. The CLI only ever applies the NextApp CR. The Go operator reconciles it into a Knative Service — wiring autoscaling, networking, and the runtime environment, and rejecting any image that is not digest-pinned. See Operator & the NextApp CRD.