@krizaka/config

InstallCopy Anchor Link

npm install @krizaka/config

Also published as subpath exports: @krizaka/config/eslint, @krizaka/config/eslint/next, @krizaka/config/eslint/krizaka-ui, @krizaka/config/eslint/no-locale-ternary, @krizaka/config/eslint/stack, @krizaka/config/eslint/ui-warnings, @krizaka/config/eslint/env-names, @krizaka/config/eslint/plugin, @krizaka/config/dependency-cruiser, @krizaka/config/covered-domains, @krizaka/config/covered-domains.json, @krizaka/config/known-violations, @krizaka/config/patterns, @krizaka/config/ratchet, @krizaka/config/prettier, @krizaka/config/tsconfig/base.json, @krizaka/config/tsconfig/react-library.json, @krizaka/config/tsconfig/next.json, @krizaka/config/tsconfig/react-native.json, @krizaka/config/editorconfig.

The shared configuration of every Krizaka JavaScript repository. ESLint flat configs (base, Next.js, the four UI rules, the three stack rules, no locale ternary), the dependency-cruiser boundary, tsconfig bases, Prettier, EditorConfig — and krizaka-ratchet, the counter that keeps the UI and stack debts from coming back.

Adopt it in three linesCopy Anchor Link

npm install -D @krizaka/config eslint typescript     # + eslint-config-next for a Next.js app, prettier if you format

// eslint.config.mjs — a Next.js app (a library: `krizakaBase` from "@krizaka/config/eslint")
import { krizakaNext } from "@krizaka/config/eslint/next";
import { krizakaUi } from "@krizaka/config/eslint/krizaka-ui";
import { noLocaleTernary } from "@krizaka/config/eslint/no-locale-ternary";
import { krizakaStack } from "@krizaka/config/eslint/stack";

export default [...krizakaNext, ...krizakaUi(), ...krizakaStack(), ...noLocaleTernary()];

// .dependency-cruiser.cjs — « Krizaka first », cycles, unresolvable imports, dev dependencies, plus the app's own rules
module.exports = { extends: "@krizaka/config/dependency-cruiser", forbidden: [] };

// tsconfig.json — base · react-library · next · react-native
{ "extends": "@krizaka/config/tsconfig/next.json", "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"] }

Prettier: export { default } from "@krizaka/config/prettier"; in prettier.config.js (120 columns, double quotes, trailing commas). EditorConfig: cp node_modules/@krizaka/config/.editorconfig ..

eslint ^9 and typescript ^5 are peer dependencies; eslint-config-next (Next.js apps) and prettier are optional peers. The plugins (typescript-eslint, eslint-plugin-react-hooks, eslint-plugin-simple-import-sort) come with the package.

What is insideCopy Anchor Link

The four UI rulesCopy Anchor Link

On every string literal inside a className (in cn(…), a ternary…), with no plugin — no-restricted-syntax selectors:

1. No raw palette colour — bg-zinc-900, text-violet-400/80: use a role of @krizaka/tailwind (bg-surface-1, text-fg-secondary, border-border-default, text-accent, text-danger).
2. No light: — a theme is a set of tokens; a dark island takes .theme-dark on its ancestor.
3. No arbitrary [var(--…)] utility — the variable has a utility in @krizaka/tailwind.
4. No template literal in className — cn(…) merges the classes and lets the override win.

krizakaUi({
  allow: ["emerald"],             // palette families tolerated for documented, isolated cases
  files: ["**/*.{jsx,tsx}"],      // default
  ignores: ["app/og/**"],         // e.g. generated OG images
  severity: "error",              // "warn" while the ratchet brings the debt down
});

Flat config replaces a rule's options instead of concatenating them: a repository that already sets no-restricted-syntax merges both lists with krizakaUiRestrictedSyntax(). no-locale-ternary is a plugin rule for that reason — it composes with anything.

The stack rulesCopy Anchor Link

From ADR-001 — the TanStack engines run headless, behind @krizaka/* facades; a product never imports them. Warnings: krizaka-ratchet counts the same patterns, so an app adopts them before it is clean and brings each count to 0 by the end of its adoption.

1. krizaka/no-fetch-in-client-effect — a fetch / krizakaFetch inside a useEffect (or useLayoutEffect) of a "use client" file: render the first screen in a Server Component, read the rest with @krizaka/query.
2. krizaka/no-local-table-or-form — a <table>, or a <form> of more than one field (native fields and the field primitives of @krizaka/ui; a hidden or submit <input> is not a field): use DataTable and createKrizakaForm. A search box or a one-field newsletter stays a plain form.

krizakaStack({
  files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"], // default
  ignores: ["packages/**"],                        // e.g. the facades of a monorepo
  severity: "warn",                                // default; "error" once the app's counts are at 0
  maxFormFields: 1,                                // default
});

« Krizaka first » — the refused imports (dependency-cruiser)Copy Anchor Link

Part of the stack ADR and of krizaka-ui#609, in one tool: dependency-cruiser carries every refused import (an import is an edge: it catches re-exports and dynamic imports, and the same file holds the layers); ESLint keeps the framework rules above. The ESLint rule krizaka/no-direct-tanstack-import is retired: @tanstack/* is krizaka-first-query.

The covered-domains map is covered-domains.json, the single source. Each domain names its Krizaka home and what is refused in an app; the preset generates krizaka-first-<domain> from it, and the page « Use Krizaka first » of ui.krizaka.com is laid out from it (coveredDomainsMarkdown()).

An entry is a package (dayjs, and its subpaths), a prefix (date-fns*) or a scope (@tanstack/*). It matches the resolved file and the module as written when it cannot be resolved (a package the app does not declare), never a local folder of the same name. A Krizaka package is exempt: it is the facade. In an app that is the packages in node_modules; in a monorepo that holds its own Krizaka packages, say where they live:

// .dependency-cruiser.cjs of a monorepo (krizaka-ui, krizaka-ts)
module.exports = require("@krizaka/config/dependency-cruiser").withOptions({ exemptFrom: ["(^|/)packages/"] });

Every message names the home and ends « Missing function? add it to the package first. » — a missing function is added to the Krizaka package, never worked around with the library. Run it with depcruise --output-type err-long <folders> to read the message (err prints the rule name only). Beside the domains, the preset owes every repository no-circular, not-to-unresolvable (declare the dependency, or fix the path; set options.tsConfig for path aliases) and not-to-dev-dep (tests, stories, scripts and tool configs may import devDependencies). Run depcruise from the workspace that owns the package.json.

Known violations (they only shrink)Copy Anchor Link

An app that adopts the rules late records what it already breaks, and the debt only goes down:

krizaka-known-violations init src app         # once, in the adoption pull request: writes .dependency-cruiser-known-violations.json
depcruise src app --config .dependency-cruiser.cjs --ignore-known .dependency-cruiser-known-violations.json   # lint: new violations fail
krizaka-known-violations check src app        # lint: also fails on a recorded violation that is fixed ("lock the gain")
krizaka-known-violations update src app       # removes the fixed ones; NEVER adds one, and fails while a new one exists

The file is the format of depcruise-baseline, so --ignore-known reads it. init refuses to overwrite it; there is no command that records a new violation. It replaces the directTanstackImport counter of krizaka-ratchet, which stays only for repositories that have not moved yet.

noLocaleTernary({ files, routing }): routing lists the files allowed to compare locales (default: proxy.ts, middleware.ts, i18n.ts, seo.ts, app/[locale]/layout.tsx, I18nProvider.tsx).

Environment variable names (krizaka/env-name)Copy Anchor Link

Environment variables are named by bounded context (krizaka/.github#46): <CONTEXT>_<THING> with CONTEXT one of APP_ DATABASE_ AUTH_ MEDIA_ MAIL_ PUSH_ PAYMENTS_ REALTIME_ ABUSE_ OBSERVABILITY_ AI_ OPERATOR_. The rule — on in krizakaBase and krizakaNext — refuses a name read through process.env.X, process.env["X"] or import.meta.env.X that starts (after NEXT_PUBLIC_, EXPO_PUBLIC_ or VITE_) with:

• a product: the organisation's name, the repository's own (the first word of its package.json name, acme-monorepo → ACME_), or one you name — a deployment already says which product it is;
• a vendor (BUNNY_, MAILGUN_, RESEND_, STRIPE_, GOOGLE_, EXPO_, REDIS_…): the vendor is a value (MEDIA_STORAGE_PROVIDER=bunny, MAIL_PROVIDER=mailgun) and its settings sit under the context (MEDIA_STORAGE_API_KEY, MAIL_API_KEY).

The platforms' own names (GITHUB_TOKEN, EAS_BUILD, …) pass. Tune it with envNames({ products, vendors, allow }) from @krizaka/config/eslint/env-names; envNamePrefixProblem(name) gives the same verdict to a script (a .env.example or deployment spec check).

The ratchetCopy Anchor Link

A repository with debt cannot turn the rules on in one pull request. The ratchet lets it adopt them now: it counts the four UI debts and the four stack debts, records the counts in lint-ratchet.json at the root, and fails when a count goes up. Every migration pull request lowers them; when a count reaches zero, the matching rule becomes a strict error.

npx krizaka-ratchet --init      # once: creates lint-ratchet.json with today's counts — commit it
npx krizaka-ratchet             # locally: compares (exit 1 when a count went up)
npx krizaka-ratchet --update    # after a migration: lowers the recorded counts (never raises them), records new counters — commit it
npx krizaka-ratchet --json      # in CI: the same check, machine-readable

The UI counters scan app/**/*.tsx, components/**/*.tsx and src/**/*.tsx by default (node_modules, dist, .next never), or the globs given on the command line; the stack counters scan every source file (js, jsx, mjs, ts, tsx, mts) of app, components, src, lib, hooks and features (stackGlobs). --init stores both in the file so that every later run counts the same set. A file written before the stack counters still checks; the next --update records them at their current value. The counts apply the regex to the whole source text — a class held in a constant or a cn() argument counts too — so the ratchet is never looser than the rule. Exit codes: 0 ok, 1 a count went up, 2 usage or file error.

// lint-ratchet.json
{
  "globs": ["app/**/*.tsx", "components/**/*.tsx", "src/**/*.tsx"],
  "stackGlobs": ["app/**/*.{js,jsx,mjs,ts,tsx,mts}", "…"],
  "allow": [],                                   // optional: same families as krizakaUi({ allow })
  "retire": ["framer-motion"],                   // optional: dependencies on their way out
  "maxFormFields": 1,                            // optional: same option as krizakaStack({ maxFormFields })
  "counters": {
    "palette": 2400, "light": 1151, "arbitraryVar": 0, "classNameTemplate": 128,
    "fetchInClientEffect": 41, "directTanstackImport": 3, "localTableOrForm": 38, "retiredImport": 4
  }
}

The CI step, after the install:

- run: npx krizaka-ratchet --json

LicenseCopy Anchor Link

Apache-2.0

ExportsCopy Anchor Link

The 0 names the package exports, read from its types.

@krizaka/config/eslintCopy Anchor Link

@krizaka/config/eslint/nextCopy Anchor Link

@krizaka/config/eslint/krizaka-uiCopy Anchor Link

@krizaka/config/eslint/no-locale-ternaryCopy Anchor Link

@krizaka/config/eslint/stackCopy Anchor Link

@krizaka/config/eslint/ui-warningsCopy Anchor Link

@krizaka/config/eslint/env-namesCopy Anchor Link

@krizaka/config/eslint/pluginCopy Anchor Link

@krizaka/config/dependency-cruiserCopy Anchor Link

@krizaka/config/covered-domainsCopy Anchor Link

@krizaka/config/covered-domains.jsonCopy Anchor Link

@krizaka/config/known-violationsCopy Anchor Link

@krizaka/config/patternsCopy Anchor Link

@krizaka/config/ratchetCopy Anchor Link

@krizaka/config/prettierCopy Anchor Link

@krizaka/config/tsconfig/base.jsonCopy Anchor Link

@krizaka/config/tsconfig/react-library.jsonCopy Anchor Link

@krizaka/config/tsconfig/next.jsonCopy Anchor Link

@krizaka/config/tsconfig/react-native.jsonCopy Anchor Link

@krizaka/config/editorconfigCopy Anchor Link

PackageCopy Anchor Link

ChangelogCopy Anchor Link

0.8.0Copy Anchor Link

Minor changes

• @krizaka/config now lives in krizaka-ts (the quality kit is not UI), with its history. Same name, same exports, same behaviour; the repository, bug tracker and homepage links change. Releases are published from krizaka-ts.

• « Krizaka first » (krizaka-ui#609, #612): the covered-domains map (covered-domains.json, dates, i18n, query, icons, ui: each names its Krizaka home and the refused imports) and the dependency-cruiser preset generated from it, one krizaka-first-<domain> rule per domain, with no-circular, not-to-unresolvable and not-to-dev-dep. The message names the Krizaka home and says « Missing function? add it to the package first. ». .withOptions({ exemptFrom }) for a monorepo's own packages. New krizaka-known-violations (init, check, update): a known-violations baseline that only shrinks. New exports @krizaka/config/covered-domains and /known-violations; dependency-cruiser is now a dependency.

  Breaking: the ESLint rule krizaka/no-direct-tanstack-import is retired (and leaves STACK_RULES): the TanStack import is krizaka-first-query in dependency-cruiser, one tool only. krizaka-no-direct-tanstack is replaced by it.

0.7.0Copy Anchor Link

Minor changes

• #496 64ede61 Thanks @krizaka-agents! - Peer range eslint: ^9 || ^10 (and @eslint/js likewise). The ESLint suite and the lint of the package pass under both ESLint 9.39 and 10.13 (krizaka-ui#141).

0.6.0Copy Anchor Link

Minor changes

• #488 c4a6ce1 Thanks @krizaka-agents! - The URL is the state, made impossible to forget (Oussama, 2026-10-22: « changer les tabs doit changer les routes »).

  • New @krizaka/ui/router: useRouteState(key, { values, default, history }) keeps a value in a search parameter, typed from an as const list (an unknown value reads as the default, the default is never written, other parameters are kept); RouteStateProvider takes your router's adapter once (the History API is the default); pure readRouteValue / writeRouteValue.
  • routeKey (+ routeValues) on Tabs.Root, Chip.Group (single) and ChoiceGrid: they bind to the URL, no useState. Local state stays for ephemeral UI only.
  • @krizaka/config: the rule krizaka/route-state-selection (in krizakaStack(), severity of the stack, only pages and route components) refuses a Tabs / Chip.Group / ChoiceGrid / SegmentedControl / ToggleGroup driven by local state without routeKey, unless the line carries // @ephemeral: <reason>; the ratchet counts it as routeStateSelection (only goes down).

0.5.0Copy Anchor Link

Minor changes

• #486 0b1d80d Thanks @krizaka-agents! - No more family switcher: krizaka.com is the only way back between the Krizaka sites (Oussama, 2026-10-22).

  • NavBar.Family is deprecated (removed in the next minor once no site uses it).
  • SiteFooter lists the family on the hub only: family now defaults to current === "krizaka", so every other site's footer holds its own columns, the legal links and one quiet « A Krizaka project » line linking to www.krizaka.com. New products prop filters the hub's Products column (krizaka.com's focus products), replacing CSS that hid links by URL.
  • @krizaka/config: the krizaka/no-family-switcher rule (an error in krizakaStack()) refuses NavBar.Family so it does not come back.

0.4.2Copy Anchor Link

Patch changes

• #467 af54020 Thanks @krizaka-agents! - Vercel is retired: its platform variable names are no longer allowed by the env-name rule (a VERCEL_ variable is refused like any vendor name).

0.4.1Copy Anchor Link

Patch changes

• #179 e3bcc51 Thanks @oussamaABID! - The documentation moved to https://ui.krizaka.com, built from this repository (apps/site) at every change: the packages' homepage (what npm shows) and READMEs point there — @krizaka/tokens to /foundations/tokens, @krizaka/icons to /foundations/icons, @krizaka/fonts to /foundations/typography, the packages without UI to /packages/<name>.

0.4.0Copy Anchor Link

Minor changes

• #169 c08ae66 Thanks @oussamaABID! - Two named ESLint rules for the adoption: krizaka/no-light-variant (refuse Tailwind light: in products — tokens do the theming) and krizaka/no-raw-palette (refuse bg-zinc-900, text-violet-400… — use a role; allow families for isolated cases), registered on the krizaka plugin and shipped as warnings by krizakaUiWarnings() (@krizaka/config/eslint/ui-warnings). krizaka-ratchet already counts the same patterns (light, palette): a product adopts the warnings now and brings both counts to 0. krizakaUi() stays the strict set.

0.3.1Copy Anchor Link

Patch changes

• #143 d0e43fd Thanks @oussamaABID! - Package homepage points to the documentation on krizaka.com (the page the npm listing links to is the one that explains the package).

0.3.0Copy Anchor Link

Minor changes

• #129 86484f5 Thanks @oussamaABID! - krizaka/env-name: environment variables are named by bounded context (krizaka/.github#46) — <CONTEXT>_<THING>, never after a product (the organisation's, the repository's own read from its package.json, or one a config names) nor a vendor (BUNNY_, MAILGUN_, GOOGLE_, EXPO_…: a vendor is a value, MAIL_PROVIDER=mailgun). It reads process.env.X, process.env["X"] and import.meta.env.X, sees through NEXT_PUBLIC_ / EXPO_PUBLIC_ / VITE_, lets the platforms' own names through (GITHUB_TOKEN, VERCEL_URL, EAS_BUILD…), and is on in krizakaBase and krizakaNext; envNames({ products, vendors, allow }) (@krizaka/config/eslint/env-names) tunes it. @krizaka/realtime's error and docs name REALTIME_REDIS_URL, @krizaka/push's docs PUSH_ACCESS_TOKEN.

0.2.0Copy Anchor Link

Minor changes

• #109 406e62c Thanks @oussamaABID! - The stack rules of ADR-001 (TanStack under @krizaka/* facades): krizakaStack() (@krizaka/config/eslint/stack) brings three warnings — krizaka/no-fetch-in-client-effect (a fetch / krizakaFetch in a useEffect of a "use client" file), krizaka/no-direct-tanstack-import (any @tanstack/* import outside a @krizaka/* package) and krizaka/no-local-table-or-form (a <table>, or a <form> of more than one field). krizaka-ratchet counts the same patterns (fetchInClientEffect, directTanstackImport, localTableOrForm) and the imports of the dependencies listed under retire (retiredImport); a lint-ratchet.json without them still checks, and --update records them. New @krizaka/config/dependency-cruiser: the shared boundary (krizaka-no-direct-tanstack) an app extends. Every krizaka/* rule now lives in one plugin object (@krizaka/config/eslint/plugin), so the configs compose.

0.1.0Copy Anchor Link

Minor changes

• #7 8446ac9 Thanks @oussamaABID! - Initial release: the shared configuration of every Krizaka JavaScript repository — ESLint flat configs (krizakaBase, krizakaNext, the four UI rules krizakaUi(options?) with a palette allowlist, noLocaleTernary), tsconfig bases (base, react-library, next, react-native), Prettier, EditorConfig, and krizaka-ratchet, the counter that fails when the UI debt goes up (--init, --update, --json).