@neon/config-runtime

@neon/config-runtime is the package the neon CLI itself uses to run a neon.ts policy: read a branch's live state, diff a policy against it, apply the result, and bundle and deploy Neon Functions. Import it directly when you're writing your own CI step or script and the CLI commands (neon config plan, neon deploy) don't fit. For example, a custom GitHub Actions job that applies a policy to a freshly created preview branch.

If you just want to run neon.ts from the command line, use the neon config / neon deploy commands instead. Reach for this package only when you need to call the same logic from your own Node.js code.

Install

npm install @neon/config-runtime

Requires Node.js 20.19 or later. Import from the /v1 subpath to pin a specific major version:

import { inspect, plan, apply } from "@neon/config-runtime/v1";

This package pulls in esbuild (a native binary) to bundle Neon Functions for deploy, so it belongs in a CLI, CI job, or deploy script, not in neon.ts itself. neon.ts should only ever import @neon/config, which has no native dependencies.

Resolving project and branch ids

Every function on this page takes projectId and a Neon branch id (br-…), not a branch name. Look these up yourself before calling in:

• neon projects list --output json and neon branches list --output json (the Neon CLI)
• The Neon API's list branches endpoint
• The .neon context file written by neon link (the CLI's own resolution mechanism, if your script runs alongside it)

Passing a branch name where an id is expected fails with a PLATFORM_BRANCH_NOT_FOUND error (see Error handling).

Quick example

import config from "../neon";
import { apply, inspect, plan } from "@neon/config-runtime/v1";

const target = { projectId: "solitary-fog-12345678", branchId: "br-cool-forest-12345678" };

const live = await inspect(target); // read the branch's current live state
const diff = await plan(config, target); // dry-run: what would apply change?
const result = await apply(config, target); // apply the policy for real

apply throws if the branch already has settings your policy would override. See apply for how to allow that.

Authentication

None of the functions on this page take a Neon session or browser login. They authenticate with a Neon API key, resolved in this order:

1. The apiKey option, if you pass one.
2. The NEON_API_KEY environment variable.
3. ~/.config/neonctl/credentials.json, written after running neon auth (or npx neonctl auth): the same file the CLI itself uses.

If none of these resolve, every function throws a PlatformError with code PLATFORM_MISSING_API_KEY and a message pointing you to console.neon.tech/app/settings/api-keys to generate a key. apiHost follows the same pattern for inspect, plan, apply, pullConfig, and pushConfig: pass it explicitly, or let it fall back to NEON_API_HOST and then Neon's production API. createBranch is the exception: CreateBranchOptions has no apiHost field, so you can't override the host per call there. It still honors NEON_API_HOST from the environment if you set it.

For CI, don't rely on the local CLI credentials fallback. A script that works on a developer machine because neon auth wrote ~/.config/neonctl/credentials.json will fail in a clean CI runner. Pass apiKey explicitly or set NEON_API_KEY in the job environment.

Pass api instead to inject your own NeonApi adapter (used internally for tests; most callers don't need this).

Operations

The three functions below mirror the Terraform mental model (inspect reads state, plan previews a diff, apply reconciles it) and are what neon config status / plan / apply call internally.

inspect

function inspect(options: ConfigOperationOptions): Promise<PulledBranchConfig>;

Reads a branch's live Neon state and reverse-engineers it into a neon.ts-shaped Config, plus raw project/branch metadata. Read-only, and never mutates anything.

Returns a PulledBranchConfig:

A pulled function is reported as { slug, name } only: the remote has no record of the local source file path, so a pulled config can't redeploy a function without you re-adding source by hand.

plan

function plan(config: Config, options: ConfigOperationOptions): Promise<PushResult>;

Computes what apply would do, without mutating anything (the equivalent of terraform plan). Takes the same options as inspect.

Returns a PushResult with the same shape as apply. On a dry run, applied describes the changes that would be applied; no remote state is modified.

apply

function apply(config: Config, options: ApplyOptions): Promise<PushResult>;

Applies a neon.ts policy to an existing branch. Never creates a project or branch: both must already exist (use createBranch to provision one from a policy). ApplyOptions extends ConfigOperationOptions with:

apply doesn't accept an interactive confirmation callback (that's only on the lower-level pushConfig), so it's either non-interactive (pass updateExisting/allowProtectedBranch up front) or it fails closed: unresolved drift throws PushConflictError (see Error handling). Note that a protected branch with no other drift is not itself blocked by allowProtectedBranch: false; that flag only matters together with the interactive confirm callback on pushConfig.

Returns a PushResult:

createBranch

function createBranch(config: Config, options: CreateBranchOptions): Promise<CreateBranchResult>;

Creates a branch from a neon.ts policy and brings it up with its declared settings in one step: it calls the Neon API directly to create the branch, then applies the rest of the policy to it with pushConfig. This is the flow neon checkout <new-name> needs when it creates a new branch, and the CLI calls this function to get it (not the other way around). Concretely, createBranch evaluates the policy with branch.exists: false (so creation-time tuning gated on !branch.exists actually resolves), creates the branch from the policy's parent (falling back to the project's default branch), then reconciles the rest of the policy onto it.

Returns { branchId, branchName, result: PushResult }. Throws a PlatformError (PLATFORM_CONFLICT) if branchName already exists, or (PLATFORM_BRANCH_NOT_FOUND) if the policy's parent names a branch that doesn't exist on the project.

Lower-level:pullConfigandpushConfig

inspect, plan, and apply are thin, intent-revealing wrappers over two lower-level primitives. Reach for these directly when you need control they don't expose: most commonly, an interactive confirmation prompt, or evaluating the branch closure as a creation (branchExists: false) so creation-time tuning resolves.

pushConfig always requires a branchId that already exists on the project; branchExists: false only changes how the policy is evaluated, not whether the branch has to exist. pushConfig never creates a branch, on dryRun or otherwise. If the branch doesn't exist yet, use createBranch instead.

pullConfig

function pullConfig(options: PullConfigOptions): Promise<PulledBranchConfig>;

Functionally identical to inspect: inspect forwards its options (projectId, branchId, api, apiKey, apiHost) to pullConfig unchanged and returns its result directly, with no other logic in between. The two names exist so call sites can read naturally (inspect next to plan/apply) while the engine module stays named after what it does.

pushConfig

function pushConfig(config: Config, options: PushConfigOptions): Promise<PushResult>;

Returns the same PushResult shape as apply. With dryRun: true, applied is the ordered list of changes that would be applied, and the function does not mutate remote state.

The engine behind plan and apply. PushConfigOptions is ApplyOptions plus:

PushConfirmContext passed to confirm:

Use confirm to render your own "are you sure?" prompt instead of failing closed with PushConflictError, for example in an interactive CLI built on top of this package.

Function bundling

Deploying a Neon Function means bundling its source into a ZIP archive. By default, apply, pushConfig, and createBranch do this with esbuild:

type FunctionBundler = (fn: ResolvedFunctionConfig) => Promise<Uint8Array>;

function buildFunctionBundle(fn: ResolvedFunctionConfig): Promise<Uint8Array>;

buildFunctionBundle is loaded lazily and only when a deploy actually bundles a function, so a caller that never deploys functions, or that supplies its own bundleFunction, never pulls esbuild's native binary into their build. Inject a custom bundler via the bundleFunction option on apply / pushConfig / createBranch when your runtime can't ship that binary, for example a single-file packaged CLI, or a restricted CI sandbox.

ResolvedFunctionConfig (what your bundler receives) has all deploy defaults already applied: slug, name, source (path to the entry file), env (resolved key/value pairs), runtime, and an optional dev block used only by neon dev.

Load aneon.tsfile

function loadConfigFromFile(options?: LoadConfigOptions): Promise<{ config: Config; resolvedPath: string }>;

Re-exported from @neon/config for convenience. Use it when your script doesn't already have a Config object in scope, for example a CI step that runs independently of a bundler that could import neon.ts directly.

Without path, it walks up from cwd looking for neon.ts / neon.mts / neon.js / neon.mjs, stopping at the first directory containing .git (monorepo-friendly: an intermediate package.json doesn't stop the walk).

A custom CI step

Putting the pieces together: a script that plans and applies a policy against a specific branch, suitable as its own CI job:

import { loadConfigFromFile, plan, apply } from "@neon/config-runtime/v1";

// Resolve these yourself: from CI variables you set, `neon branches list --output json`,
// or the Neon API. This package never reads `.neon` or `NEON_*` (besides NEON_API_KEY / NEON_API_HOST).
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;
const shouldApply = process.env.NEON_APPLY === "true";

const { config } = await loadConfigFromFile();

// NEON_API_KEY in the environment is picked up automatically, so there's no need to pass apiKey.
const target = {
  projectId,
  branchId,
  updateExisting: true,
  allowProtectedBranch: true,
};

const planned = await plan(config, target);
console.log(`Plan: ${planned.applied.length} change(s) for ${planned.branchName}`);

if (!shouldApply) {
  console.log("Dry run only. Set NEON_APPLY=true to apply this plan.");
  process.exit(0);
}

const result = await apply(config, target);

console.log(`Applied ${result.applied.length} change(s) to ${result.branchName}`);

Run it with tsx or after compiling with tsc, the same as any Node.js script:

npx tsx scripts/deploy-branch.ts

Error handling

Every error this package throws extends PlatformError (also re-exported here from @neon/config), which carries a stable code string plus optional details. Prefer isPlatformError(err) over err instanceof PlatformError: a neon.ts loaded through the internal TypeScript loader (jiti) imports its own copy of this package, so an error it throws can fail instanceof across that boundary. isPlatformError checks the code string instead, which survives it.

The subclasses relevant to programmatic use:

A ConflictReport (on PushConflictError.conflicts and PushResult.conflicts) has kind, identifier, field, current, desired, and a human-readable reason.

Related

• neon.ts reference: the policy this package operates on, and the neon config / neon deploy CLI commands that wrap it.
• neon-pkgs source on GitHub.