@ingram-tech/nk-dev 0.13.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +21 -21
  2. package/guide.md +4 -6
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @ingram-tech/nk-dev
2
2
 
3
- The nextkit **dev toolchain in one package**. Everything a site needs at
4
- development time — and nothing that ships to production — lives here:
3
+ The nextkit dev toolchain in one package. Everything a site needs at development
4
+ time, and nothing that ships to production:
5
5
 
6
6
  - the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `ast-grep` / `migrations` / `check` / `type-check` / `test` / `build`, plus
7
7
  `nk doctor`);
@@ -12,8 +12,8 @@ development time — and nothing that ships to production — lives here:
12
12
  - **`nk init`**, which scaffolds a site to use all of the above.
13
13
 
14
14
  It's a single `devDependency` and pulls the toolchain (oxlint, oxfmt, tsc,
15
- vitest, jsdom, jest-dom, knip) as hard dependencies — so one install gives you
16
- the whole stack instead of re-listing each tool per site.
15
+ vitest, jsdom, jest-dom, knip) as hard dependencies, so one install gives you the
16
+ whole stack instead of listing each tool in every project.
17
17
 
18
18
  > **Runtime vs dev-time.** nk-dev is the *dev-time* bundle. Runtime features
19
19
  > (`@ingram-tech/nk-email`, `nk-db`, `nk-auth`, …) stay separate packages that
@@ -33,18 +33,18 @@ bun install # the prepare script wires the git hook
33
33
  | File | What |
34
34
  | --- | --- |
35
35
  | `.oxlintrc.json` | `extends` the shared oxlint rules (relative path — oxlint doesn't resolve package specifiers) |
36
- | `.oxfmtrc.json` | a copy of the house format config (oxfmt has no `extends`) |
36
+ | `.oxfmtrc.json` | a copy of the shipped format config (oxfmt has no `extends`) |
37
37
  | `tsconfig.json` | `extends` `@ingram-tech/nk-dev/tsconfig/nextjs.json` + the site's own `include`/`paths` |
38
38
  | `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` |
39
39
  | `.githooks/pre-commit` + `prepare` script | oxfmt format-on-commit |
40
40
  | `CLAUDE.md` | the agent-guide `@import` |
41
41
 
42
42
  It also prints a `vitest.config.ts` snippet (`mergeConfig(nextkitTestConfig, {})`
43
- from `@ingram-tech/nk-dev/vitest`) rather than writing the file — add it only if
44
- you test with Vitest (many sites use `bun:test`).
43
+ from `@ingram-tech/nk-dev/vitest`) rather than writing the file. Add it only if
44
+ you test with Vitest.
45
45
 
46
- Everything is `extends`-based, so the house config is enforced by default but
47
- overridable — layer your own rules on top, or replace a stub entirely (e.g. drop
46
+ Everything is `extends`-based, so the shipped config applies by default and stays
47
+ overridable: layer your own rules on top, or replace a stub entirely (e.g. drop
48
48
  in a `biome.json` instead of the oxlint/oxfmt stubs).
49
49
 
50
50
  ## The `nk` command
@@ -65,12 +65,12 @@ Point your package.json scripts at it:
65
65
  }
66
66
  ```
67
67
 
68
- `nk` shells out to the site's own `bun x`-resolved tools (oxlint, oxfmt, Next,
69
- tsc), so versions stay under each site's control — nk just orchestrates.
68
+ `nk` shells out to the project's own `bun x`-resolved tools (oxlint, oxfmt, Next,
69
+ tsc), so versions stay under your control. nk only orchestrates.
70
70
 
71
71
  > **`nk` is optional.** It only orchestrates the standard commands; it never
72
- > wraps or intercepts the Next.js build. Every site must stay fully buildable and
73
- > runnable with plain `next build` / `next dev` if `nk` is removed — see the
72
+ > wraps or intercepts the Next.js build. A site stays fully buildable and
73
+ > runnable with plain `next build` / `next dev` if `nk` is removed. See the
74
74
  > [`nk` carve-out](https://github.com/ingram-technologies/nextkit/blob/main/docs/philosophy.md).
75
75
  > The orchestration tests in this package check that the formatter resolves to
76
76
  > standard oxlint/oxfmt invocations and nothing more.
@@ -92,8 +92,8 @@ tsc), so versions stay under each site's control — nk just orchestrates.
92
92
  `DATABASE_URL`, then `next dev --turbopack`. No Docker, no daemon.
93
93
  - **Plain** — otherwise just `next dev` (static/marketing sites with no DB).
94
94
  - **`nk format` / `nk format --check`** — formats code (JS/TS/JSON/CSS) with
95
- oxfmt. `--check` verifies without writing (CI). SQL isn't formatted — it's
96
- generated (drizzle migrations, `pg_dump` baselines, pglite fixtures).
95
+ oxfmt. `--check` verifies without writing (CI). SQL isn't formatted; see
96
+ [Why no SQL formatting?](#why-no-sql-formatting).
97
97
  - **`nk lint`** — `oxlint`.
98
98
  - **`nk knip`** — `knip` (unused dependencies / exports / files).
99
99
  - **`nk migrations [--check|--reseal|--ddl]`** — guard the `drizzle/` migration
@@ -132,9 +132,9 @@ tsc), so versions stay under each site's control — nk just orchestrates.
132
132
 
133
133
  ## Why no SQL formatting?
134
134
 
135
- oxfmt is the formatter for code, and it can't format SQL — but nk-dev doesn't
136
- format SQL at all. The SQL in our repos is ~entirely generated (drizzle
137
- migrations, `pg_dump` baselines, pglite fixtures), so formatting it only churned
138
- generated files and crashed on psql directives (`\restrict`) for no gain. nk-dev
139
- therefore carries no `prettier` dependency; if a site has a leftover
140
- `.prettierignore`, `nk doctor --fix` removes it.
135
+ oxfmt can't format SQL, and nk-dev doesn't format it by another route either. In
136
+ a nextkit project the SQL is nearly all generated (drizzle migrations, `pg_dump`
137
+ baselines, pglite fixtures), so formatting it only churned generated files and
138
+ crashed on psql directives (`\restrict`) for no gain. nk-dev therefore carries no
139
+ `prettier` dependency; if a project has a leftover `.prettierignore`,
140
+ `nk doctor --fix` removes it.
package/guide.md CHANGED
@@ -9,10 +9,9 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
9
9
  - **Public contact/signup forms MUST use `@ingram-tech/nk-forms`** —
10
10
  `handleFormSubmission` server-side (rate-limit → bot gate → validate →
11
11
  escaped-email deliver → uniform 200) and `useFormSubmit` + `HoneypotInput`
12
- client-side. It layers over `@ingram-tech/bot-protection`, which stays the
13
- primitive for guarding *non-form* endpoints (a checkout, an authed route) —
14
- call `checkBot` / `verifyHuman` directly there. Never ship a public form
15
- without the bot gate.
12
+ client-side. For guarding a *non-form* endpoint (a checkout, an authed
13
+ route), call nk-forms' `checkBot` / `verifyHuman` directly instead of the
14
+ pipeline. Never ship a public form without the bot gate.
16
15
  - **Send email only via `@ingram-tech/nk-email`** — never add another mail client.
17
16
  - **Never trust an external request body's shape — validate it with Zod, never
18
17
  `as`-cast it.** Every `/api` route and webhook handler takes untrusted input;
@@ -155,8 +154,7 @@ tool instead). One-off single-file edits: just edit the file.
155
154
  - `@ingram-tech/nk-db` — Postgres data layer: `createPool` (one TLS-aware pool) + `createQueries` (raw SQL) + `createDb` (Drizzle), the PGlite dev/test harness at `@ingram-tech/nk-db/pglite`, the prefixed-id codec (the standalone `id758` package) at `@ingram-tech/nk-db/id`, and the drift-aware migration runner at `@ingram-tech/nk-db/migrate`
156
155
  - `@ingram-tech/nk-api` — the standard HTTP API seam (Hono + `@hono/zod-openapi`): one `{ error, details? }` envelope, `createApiApp` / `createRouter`, auth + multi-tenant resource-scope middleware, pagination helpers, and an emitted OpenAPI/Swagger doc. Reach for it instead of hand-rolling route handlers
157
156
  - `@ingram-tech/nk-billing` — Stripe primitives: subscriptions, a Stripe-side wallet, and an optional Postgres credit ledger behind the `/credits` subpath. Prices resolve at runtime by Stripe `lookup_key` — **never hardcode a price id**, so test and live share one code path
158
- - `@ingram-tech/bot-protection` — invisible form protection (honeypot + timing + Vercel BotID); the primitive nk-forms builds on, used directly only for non-form endpoints
159
- - `@ingram-tech/nk-forms` — the public contact/signup submission pipeline over bot-protection + nk-email: `handleFormSubmission` (rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, `mintFormToken`, and `useFormSubmit` / `HoneypotInput` (`/react`). Reach for it instead of wiring bot-protection by hand
157
+ - `@ingram-tech/nk-forms` — the public contact/signup submission pipeline: `handleFormSubmission` (rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, `mintFormToken`, and `useFormSubmit` / `HoneypotInput` (`/react`). It owns the invisible bot-protection layers too (honeypot + signed timing token + Vercel BotID); `verifyHuman` / `checkBot` are exported from the root for non-form endpoints
160
158
  - `@ingram-tech/nk-i18n` — type-safe, English-as-key i18n: the English source text *is* the key (no `en.json`), ICU MessageFormat, colocated JSON catalogs, plus **locale URL routing** (`defineLocaleRouting` + a fixed URL→account→cookie→`Accept-Language`→country precedence, wired to Next at `/next`). A URL that names a locale must serve it with a 200 — never redirect `?hl=fr` away, or every hreflang annotation on the site points at a URL that doesn't serve the language it claims. See `docs/i18n-routing.md`
161
159
  - `@ingram-tech/nk-marketing` — Postgres-backed marketing & lifecycle email: contacts + consent, newsletter broadcast audiences, and idempotent triggered campaigns, with RFC 8058 one-click unsubscribe
162
160
  - `@ingram-tech/nk-seo` — SEO toolkit: metadata factory, JSON-LD builders, sitemap/robots routes, hreflang + canonical links, and an OG image template
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.13.0",
3
+ "version": "0.13.1",
4
4
  "description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
5
5
  "license": "MIT",
6
6
  "type": "module",