Skip to main content

Next.js + TypeScript (Fully Local)

This tutorial gets you to a working Next.js + TypeScript app with type-safe feature flags and dynamic configs, without signing up for a Quonfig account, without an API key, and without any network connection to quonfig.com. Everything runs against JSON files in a local git repo.

By the end you'll have:

  • A Next.js 15+ app with the App Router
  • A Quonfig workspace (./quonfig/) checked into the same git repo
  • A type-safe SDK client generated by qfg generate
  • A server component reading a feature flag from local files

If you'd rather see the bigger picture first, read the Open Source / Fully Local how-to.

Prerequisites​

  • Node.js 20.9 or newer (the CLI requires it)
  • A fresh terminal

1. Scaffold a Next.js app​

npx create-next-app@latest quonfig-local-demo \
--typescript --app --no-tailwind --no-eslint --no-src-dir --import-alias "@/*"
cd quonfig-local-demo

2. Install the Quonfig CLI​

npm install -g @quonfig/cli

You do not need to run qfg login. Skip past anything in the docs that mentions it.

3. Create a workspace inside your repo​

mkdir quonfig && cd quonfig
qfg init --samples
cd ..

qfg init --samples lays down a complete workspace under ./quonfig/:

quonfig/
├── quonfig.json
├── README.md
├── CLAUDE.md
├── AGENTS.md
├── feature-flags/
│ └── example.dark-mode.json
├── configs/
│ └── example.greeting.json
├── segments/
│ └── example.beta-users.json
├── schemas/
├── log-levels/
│ └── log-level.example.app.json
└── .git/ # yes, the workspace gets its own git repo

The pre-commit hook in quonfig/.git/hooks/pre-commit runs qfg verify automatically on every commit inside the workspace.

If you'd rather keep everything in a single git repo, delete quonfig/.git and let your Next.js repo track those JSON files directly.

4. Add a feature flag​

For a quick demo, just use the sample dark-mode flag. Open quonfig/feature-flags/example.dark-mode.json and confirm it looks like:

{
"key": "example.dark-mode",
"type": "feature_flag",
"valueType": "bool",
"description": "Enable dark mode UI.",
"default": {
"rules": [
{ "criteria": [{ "operator": "ALWAYS_TRUE" }], "value": { "type": "bool", "value": false } }
]
},
"environments": [
{
"id": "staging",
"rules": [
{ "criteria": [{ "operator": "ALWAYS_TRUE" }], "value": { "type": "bool", "value": true } }
]
}
],
"variants": []
}

The default returns false; the staging environment override returns true. We'll run in the development environment in step 7, so we get the default — flip the inner value in default.rules[0].value to flip the result.

Validate the workspace:

cd quonfig && qfg verify && cd ..

You should see no errors. qfg verify runs entirely locally — no network.

5. Install the Node SDK​

npm install @quonfig/node

6. Generate typed accessors​

From the project root:

cd quonfig
qfg generate --targets node-ts -o ../generated
cd ..

Because the current directory has a quonfig.json, qfg generate auto-detects the local workspace and reads the files directly — no login, no network. You should see:

Using local workspace at /…/quonfig-local-demo/quonfig (auto-detected quonfig.json).
Generating node-ts code for configs...

That creates ./generated/quonfig-server.ts and ./generated/quonfig-server-types.d.ts. Re-run this whenever you change a flag or config.

7. Bootstrap the SDK against the local directory​

Create lib/quonfig.ts:

// lib/quonfig.ts
import { Quonfig } from "@quonfig/node";
import path from "node:path";

const quonfig = new Quonfig({
// Point the SDK at the JSON files on disk.
datadir: path.join(process.cwd(), "quonfig"),
// Pick which environment overrides to apply.
environment: process.env.QUONFIG_ENVIRONMENT ?? "development",
});

let initPromise: Promise<void> | undefined;

export async function getQuonfig() {
if (!initPromise) initPromise = quonfig.init();
await initPromise;
return quonfig;
}

With datadir set and no sdkKey passed, the SDK runs in fully local mode: it reads from disk, evaluates in memory, and makes no network calls. There's no stream or poll to turn off; datadir mode never starts them. (If you later add an SDK key, usage telemetry is sent even in datadir mode; see Local Workspace.)

The initPromise lazy-initializes once per server process — Next.js reuses the same Node module instance across requests in production.

8. Use the flag in a server component​

Edit app/page.tsx:

// app/page.tsx
import { getQuonfig } from "@/lib/quonfig";

export default async function Home() {
const quonfig = await getQuonfig();
const darkMode = quonfig.getBool("example.dark-mode");
const greeting = quonfig.getString("example.greeting");

return (
<main style={{ padding: 32, background: darkMode ? "#111" : "#fff", color: darkMode ? "#eee" : "#111" }}>
<h1>{greeting}</h1>
<p>Dark mode is <strong>{darkMode ? "on" : "off"}</strong>.</p>
<p>Flip the flag value in <code>quonfig/feature-flags/example.dark-mode.json</code> and restart the dev server to see it change.</p>
</main>
);
}

The SDK exposes getBool, getString, getNumber, getJSON, getStringList, and isEnabled (plus *Details variants). If you want type-safe accessors per-flag instead of stringly-typed keys, use the QuonfigTypesafeNode wrapper generated by qfg generate in step 6 — see the Node SDK docs for the typed pattern.

9. Run it​

npm run dev

Visit http://localhost:3000. The page renders using the value of example.dark-mode from your local JSON file.

Editing flags in dev

By default the SDK loads the workspace once per Node module instance, so editing quonfig/feature-flags/example.dark-mode.json while the dev server is running won't be reflected on reload. Either restart the dev server (Ctrl-C then npm run dev), or add dataDirAutoReload: true to the options in lib/quonfig.ts so the SDK watches the directory and reloads when you save. For example, dataDirAutoReload: process.env.NODE_ENV !== "production" turns it on only in development. See the Open Source / Fully Local how-to for details.

If port 3000 is busy, Next.js falls back to 3001 (or higher) — watch the boot log for the actual URL.

10. Commit and ship​

The whole workspace is just files. By default qfg init makes quonfig/ its own git repo so the pre-commit hook works. The cleanest pattern for this tutorial is a single repo at the project root — drop the inner .git and let the outer Next.js repo track everything:

rm -rf quonfig/.git
git add quonfig generated lib app
git commit -m "Add feature flags via local Quonfig workspace"

(If you'd rather keep quonfig/ as a separate repo — e.g. you want to share configs across multiple apps — leave its .git in place, commit inside it separately, and add quonfig as a git submodule of the outer repo.)

Removing quonfig/.git also removes its pre-commit hook, so nothing runs qfg verify for you anymore. Add it to CI instead:

npx -y @quonfig/cli verify quonfig

Ship the config files with the build​

The SDK reads quonfig/ at runtime from a path it builds itself (path.join(process.cwd(), "quonfig")). Next.js output file tracing can't see that read, so on Vercel, or with output: "standalone", the JSON files are left out of the deployed bundle. The SDK then starts with no configs. Tell Next.js to include them:

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
outputFileTracingIncludes: {
"/*": ["./quonfig/**/*.json"],
},
};

export default nextConfig;

You don't need this for next start on a machine that has the full repo checked out. There, the files are already on disk.

Push the repo wherever you want. In production, set QUONFIG_ENVIRONMENT=production and the SDK applies the production environment overrides from your JSON files. That's the entire deployment loop.

Where to go from here​

  • Editor support: add "$schema": "https://api.quonfig.com/schemas/v1/stored-config.json" at the top of each JSON file to get autocomplete and validation in VS Code / Cursor / Zed. The sample files from qfg init --samples don't include it. Confirm it works by typing "operator": "PROP_ inside a rule's criteria array.
  • AI agents: qfg init writes a CLAUDE.md and AGENTS.md inside quonfig/. Point your agent at the workspace directory and it knows to edit JSON directly, run qfg verify, and use qfg config-schema to look up valid shapes. It will not try to call hosted-only commands like qfg create or qfg push.
  • More environments: list your environments in quonfig/quonfig.json, for example "environments": ["development", "staging", "production"], and add per-environment overrides inside each flag's environments array. While the list is empty the SDK accepts any environment name. Once it has entries, every environment the app runs as must be in it, or init() throws. That includes development, the default in lib/quonfig.ts. See Local Workspace for how environments work in datadir mode and what (if anything) the SDK sends over the network.
  • Targeting: use operators like PROP_IS_ONE_OF, PROP_MATCHES, IN_SEG, or IN_INT_RANGE to roll out to specific users. Run qfg config-schema to see the full operator list.
  • Upgrade later: if you want a UI, real-time SSE delivery, telemetry, or audit history, sign up for a Quonfig account and run qfg push from the same repo. The file format is identical.