Getting started

Take an existing Next.js app from next build to a scale-to-zero Knative service. knext uses the official Next.js Deployment Adapter API — no fork, no custom runtime.

Prerequisites. A Kubernetes cluster with Knative Serving installed, Next.js 16.x, a container registry, and an object-storage bucket (gcs, s3, or minio).

Runtime requirement (current). The kn-next CLI ships with a #!/usr/bin/env node shebang and a kn-next bin, but the package is not published to npm yet. Until then, run it from a checkout of the knext repo rather than npx kn-next.

1 · Point Next.js at the adapter

Reference the knext adapter from your next.config.ts. The adapter forces output: 'standalone' at build time.

next.config.ts

import path from 'node:path';
import type { NextConfig } from 'next';

const config: NextConfig = {
  output: 'standalone',
  experimental: {
    // knext ships the official NextAdapter as a package export; a thin local
    // re-export file points experimental.adapterPath at it.
    adapterPath: path.resolve(import.meta.dirname, 'next-adapter.ts'),
  },
};

export default config;

next-adapter.ts

// thin re-export of the package-shipped knext adapter
import adapter from '@knext/core/adapter';
export default adapter;

2 · Write the deploy config

knext reads a typed kn-next.config.ts. The config type is KnativeNextConfig, exported from @knext/core. The minimum valid config requires name, registry, and a storage block with provider, bucket, and publicUrl.

kn-next.config.ts

import type { KnativeNextConfig } from '@knext/core';

const config: KnativeNextConfig = {
  name: 'storefront',
  registry: 'registry.example.com/storefront',
  storage: {
    provider: 'gcs', // one of: gcs | s3 | minio
    bucket: 'storefront-assets',
    publicUrl: 'https://storage.googleapis.com/storefront-assets',
  },
  scaling: { minScale: 0, maxScale: 20 }, // minScale 0 = scale to zero
};

export default config;

storage.provider is validated against gcs | s3 | minio. The StorageProvider type also lists azure, but the CLI validator does not accept it — an azure config is rejected at load time. Don't use it. See Multi-cloud deploy.

3 · Build, push, deploy

The kn-next CLI surface is: deploy (the default — build → push → apply the NextApp CR), build, cleanup, and rollback. Validation runs automatically when the config loads.

shell

# build + push (digest is resolved automatically) and apply the NextApp CR
$ kn-next deploy --registry registry.example.com/storefront

✓ image  registry.example.com/storefront@sha256:9f1c...
✓ NextApp/storefront applied
✓ url    https://storefront.apps.example.com  (scaled to 0)

kn-next deploy flags: -r/--registry, -b/--bucket, -t/--tag, -n/--namespace, --skip-build, --skip-upload, --dry-run (print the CR without applying), -h/--help, -v/--version.

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, optionally the bytecode-cache volume, and rejecting any image that is not digest-pinned. See Operator & the NextApp CRD.

Other commands

kn-next build — run next build (standalone) and upload static assets.
kn-next rollback [app] --to <revision> (optionally --canary <n>) — shift traffic on the NextApp CR's spec.traffic back to a prior revision, with canary support.
kn-next cleanup — delete the NextApp CR; the operator's finalizer clears external state.

Getting started

1 · Point Next.js at the adapter

2 · Write the deploy config

3 · Build, push, deploy

Other commands

On this page