@ingram-tech/nk-dev

The nextkit dev toolchain in one package. Everything a site needs at development time, and nothing that ships to production:

• the nk CLI (nk dev / format / lint / knip / ast-grep / migrations / check / type-check / test / build, plus nk doctor);
• the shared oxlint + oxfmt, TypeScript, and Vitest config;
• knip (unused dependency / export / file detection), bundled and run by nk check;
• the oxfmt format-on-commit git hook (nextkit-format-staged);
• the AI agent guide (guide.md) imported into a site's CLAUDE.md;
• nk init, which scaffolds a site to use all of the above.

It's a single devDependency and pulls the toolchain (oxlint, oxfmt, tsc, vitest, jsdom, jest-dom, knip) as hard dependencies, so one install gives you the whole stack instead of listing each tool in every project.

Runtime vs dev-time. nk-dev is the dev-time bundle. Runtime features (@ingram-tech/nk-email, nk-db, nk-auth, …) stay separate packages that peer-depend on next/react. See the dev-toolchain carve-out in philosophy.md.

Install

bun add -d @ingram-tech/nk-dev
bun x nk init
bun install   # the prepare script wires the git hook

nk init writes the config files (and skips any that already exist):

| File | What | | --- | --- | | .oxlintrc.json | extends the shared oxlint rules (relative path — oxlint doesn't resolve package specifiers) | | .oxfmtrc.json | a copy of the shipped format config (oxfmt has no extends) | | tsconfig.json | extends @ingram-tech/nk-dev/tsconfig/nextjs.json + the site's own include/paths | | knip.json | seed config (knip has no shareable config): gates on dependency/file hygiene, with unused exports/types off (noisy); ignores @ingram-tech/nk-dev | | .githooks/pre-commit + prepare script | oxfmt format-on-commit | | CLAUDE.md | the agent-guide @import |

It also prints a vitest.config.ts snippet (mergeConfig(nextkitTestConfig, {}) from @ingram-tech/nk-dev/vitest) rather than writing the file. Add it only if you test with Vitest.

Everything is extends-based, so the shipped config applies by default and stays overridable: layer your own rules on top, or replace a stub entirely (e.g. drop in a biome.json instead of the oxlint/oxfmt stubs).

The nk command

Point your package.json scripts at it:

{
	"scripts": {
		"dev": "nk dev",
		"format": "nk format",
		"lint": "nk lint",
		"check": "nk check",
		"type-check": "nk type-check",
		"test": "nk test",
		"build": "nk build"
	}
}

nk shells out to the project's own bun x-resolved tools (oxlint, oxfmt, Next, tsc), so versions stay under your control. nk only orchestrates.

nk is optional. It only orchestrates the standard commands; it never wraps or intercepts the Next.js build. A site stays fully buildable and runnable with plain next build / next dev if nk is removed. See the nk carve-out. The orchestration tests in this package check that the formatter resolves to standard oxlint/oxfmt invocations and nothing more.

Commands

• nk init — scaffold this project to use nextkit (see above). Idempotent: skips files that already exist.
• nk doctor [--fix] — report drift from the canonical nk-dev toolchain (superseded deps, config extends, package.json scripts, the agent-guide import, a stale .prettierignore, an unsealed migration chain and the DDL in it drizzle can't model, a page under app/auth/ shadowing a Better Auth endpoint — static segments beat the [...all] catch-all, so such a page silently 405s the endpoint); --fix applies the auto-fixable findings.
• nk dev — start the Next dev server on the golden-path local database (see db-package.md):
  • PGlite — if @ingram-tech/nk-db's nk-pglite-dev bin resolves, hand off to it: boot Postgres-in-WASM, apply the drizzle/ migrations, set DATABASE_URL, then next dev --turbopack. No Docker, no daemon.
  • Plain — otherwise just next dev (static/marketing sites with no DB).
• nk format / nk format --check — formats code (JS/TS/JSON/CSS) with oxfmt. --check verifies without writing (CI). SQL isn't formatted; see Why no SQL formatting?.
• nk lint — oxlint.
• nk knip — knip (unused dependencies / exports / files).
• nk migrations [--check|--reseal|--ddl] — guard the drizzle/ migration chain, with no database involved. Verifies each file against the hashes in drizzle/_seal.json and seals newly generated ones; --check verifies without writing (what nk check runs); --reseal rewrites every hash for a deliberate squash; --ddl lists the migrations carrying DDL drizzle's snapshot can't model. Details in db-package.md. A no-op on sites without a migration journal.
• nk ast-grep [...] — structural search & rewrite of TS/TSX by AST pattern, via the vendored ast-grep (args passed through to it). For large mechanical refactors — import rewrites, API renames, call-shape changes — instead of hand-editing or sed. The workflow (search → preview → apply → nk format + nk type-check) and its syntactic-not-semantic limits live in the codemod skill, skills/ts-codemod.md.
• nk check — oxlint + oxfmt --check + knip (only when the repo has a knip config) + the agent-guide import gate + the migration seal. The CI gate; runs every checker and reports them all before failing.
• nk type-check — next typegen && tsc --noEmit.
• nk test [...] — vitest run, extra args passed through.
• nk build [...] — next build, extra args passed through.

Exports

"@ingram-tech/nk-dev/oxlintrc.json"          // oxlint rules (extend via relative path)
"@ingram-tech/nk-dev/oxfmtrc.json"           // oxfmt config (copy; no extends)
"@ingram-tech/nk-dev/tier-b.json"            // stricter opt-in lint tier
"@ingram-tech/nk-dev/tsconfig/base.json"     // base TS config
"@ingram-tech/nk-dev/tsconfig/nextjs.json"   // Next.js TS config (also "/tsconfig")
"@ingram-tech/nk-dev/vitest"                 // nextkitTestConfig preset
"@ingram-tech/nk-dev/vitest/setup"           // Vitest setup (jest-dom + Next mocks)
"@ingram-tech/nk-dev/guide.md"               // the AI agent guide

Why no SQL formatting?

oxfmt can't format SQL, and nk-dev doesn't format it by another route either. In a nextkit project the SQL is nearly all generated (drizzle migrations, pg_dump baselines, pglite fixtures), so formatting it only churned generated files and crashed on psql directives (\restrict) for no gain. nk-dev therefore carries no prettier dependency; if a project has a leftover .prettierignore, nk doctor --fix removes it.