Linting and formatting
Brix manages Oxfmt, Oxlint, type-aware linting, and Brix-specific rules as one versioned project
policy. Use brix format to write formatting changes and brix check to verify formatting, lint,
types, and project structure. Do not install or invoke the underlying tools separately.
For the normal repair loop, run brix format, review the diff, then run brix check. Reach for
configuration only when the team intends to change policy—not to hide a one-off diagnostic. In a
workspace, make that decision at the root unless a member genuinely owns a separate boundary.
Keep native configuration files
#A standalone project keeps oxfmt.config.mts and oxlint.config.mts at its root. They call helpers
from the exact installed Brix version, so command-line checks and the official Oxc editor extension
use the same baseline:
import { defineBrixOxfmtConfig } from "brix/config";
export default defineBrixOxfmtConfig();
import { defineBrixOxlintConfig } from "brix/config";
export default defineBrixOxlintConfig();
Keep these executable native configs. Do not move formatting or lint options into
vite.config.ts, replace the helpers with copied defaults, or add legacy .oxfmtrc.json and
.oxlintrc.json files. Brix maintains the project-local Oxc declarations needed by editors; select
Oxc as the formatter in personal editor settings rather than committing editor preferences for the
team.
defineBrixOxfmtConfig accepts native Oxfmt options, appends project ignores after the managed
**/dist/**, **/.brix/**, **/styled-system/**, and **/src/env.generated.d.ts ignores, and
preserves project overrides. defineBrixOxlintConfig
accepts native Oxlint categories and options; project rules merge over managed rules, jsPlugins
append without removing Brix's plugin, and project ignores and overrides follow the managed ones.
A top-level project no-restricted-imports entry also applies under src/: Brix appends its
paths, patterns, and directly passed restricted paths to the managed import boundaries. Those
boundaries are errors, so a project restriction set to "warn" is reported as an error under
src/. Do not set that rule in
a project override, because an override's entry replaces the managed boundaries for the files it
matches.
The managed lint ignores also cover generated Panda output, src/env.generated.d.ts, and MSW's
generated mockServiceWorker.js.
Managed commands select the native config explicitly: the standalone project's own file, or the nearest member config within its Brix workspace. A missing config is an error, not permission to inherit a config from an unrelated parent repository. Workspace file-formatting operations also reject paths outside their root.
This is not complete filesystem isolation. The pinned Oxc tools independently consult ancestor
Git-ignore files, and Oxfmt also reads ancestor .editorconfig files. Brix's explicit formatter
defaults override supported EditorConfig properties, but parent Git-ignore rules can still exclude
local files from directory-based formatting or linting.
Understand the managed lint baseline
#The baseline enforces Oxlint's correctness category, type-aware checks, and application
architecture. Any warning fails brix check (maxWarnings: 0). Under src/, it rejects direct
imports of framework-owned dependencies, CommonJS require(), Brix test entry points and the
#brix/test harness binding in production modules, deployment tooling (brix/env/upload and
brix/artifacts) in runtime modules, the script environment loader outside src/env.script.ts
(brix/env/script) and outside scripts and tests (#brix/env/script), and parent-relative imports
from src/features/**. Tests may import from brix/test and #brix/test; application
code should use the supported brix/* facades. brix doctor additionally checks imports, exports,
statically known dynamic imports, and require() calls, so lint is not a substitute for diagnosis.
The five anti-slop Brix rules are errors by default:
brix/no-unknown-type-aliaseskeeps genuinely untrusted values visiblyunknownuntil validated.brix/no-widen-then-assertprevents erasing a known immutable value's type and asserting it back.brix/no-reflect-getprefers typed property access overReflect.get.brix/no-reflect-applyprefers typed calls overReflect.apply.brix/no-module-mockingprevents Vitest or Jest module replacement (mock,doMock,setMock,unstable_mockModule), including throughbrix/test,globalThis.vi, type assertions, and(0, vi.mock)indirection.
Runtime modules under src/ use named exports (import/no-default-export). Declaration files,
colocated *.stories.*, and *.config.* tool configs under __fixtures__/ are exempt; root tool
configs remain free to use required default exports. This also applies to workspace member sources.
Type checking uses the selected TypeScript baseline. The application and React application
baselines include Vite's client declarations, so import "./app.css", ?url and ?raw asset
imports, and import.meta.env type-check without adding Vite as a project dependency. The library
baseline includes Node's declarations from Brix, so console, timers, URL, fetch, and node:*
imports type-check without adding @types/node; the UI-library baseline uses DOM declarations
instead. Baselines add these declarations through files, so keep an explicit include in the
project tsconfig.json.
Upstream type-aware rules own promise safety, not method-name matching: typescript/no-misused-promises
rejects an async callback passed to synchronous ResultPromise.tap; use tapAsync instead.
typescript/no-floating-promises rejects an unawaited async browser assertion; await the assertion.
The latter comes from the correctness category with the managed TypeScript plugin.
Compile-only *.test-d.ts files are exempt from floating-promise checks: their calls test types
without executing asynchronous work. Runtime tests retain the check. Test imports also follow the
managed Node/browser boundary.
typescript/ban-ts-comment prohibits @ts-ignore and @ts-nocheck. A deliberate
@ts-expect-error needs a description (at least three characters). Brix does not globally ban
any: malformed-input tests and some integration boundaries still need deliberate escape hatches.
The generated src/env.generated.d.ts is excluded from lint and formatting: Varlock owns its
suppression header, brix env types writes its canonical formatting, and doctor separately verifies that its declarations match the authored environment schema.
Runtime validation, unknown boundary parameters, typeof, vi.fn, and vi.spyOn remain valid.
For tests, exercise routes through the route harness, mock HTTP consumed
by clients with MSW, or use an existing dependency-injection seam instead of replacing a module.
Optional project-policy rules use the same brix/ prefix: no-chained-type-assertions,
no-conditional-empty-object-spread, no-known-value-widening, no-object-parameters,
no-runtime-typeof, no-shape-in-symbol-names, no-unknown-parameters, no-unknown-returns,
no-unsafe-dictionary-type, and require-safety-comment-for-type-assertion. They are not managed
defaults; enable only rules that express a deliberate team policy.
Configure shared policy and scoped exceptions
#Pass native options to the helper. Prefer overrides when policy applies only to particular code:
import { defineBrixOxlintConfig } from "brix/config";
export default defineBrixOxlintConfig({
rules: { "no-console": "error" },
overrides: [
{
files: ["src/domain/**/*.ts"],
rules: { "brix/no-unsafe-dictionary-type": "error" },
},
{
files: ["scripts/**/*.ts"],
rules: { "no-console": "off" },
},
],
});
Globs are relative to the config file. A genuine one-statement exception should be narrower than an override and explain the invariant it preserves:
// eslint-disable-next-line brix/no-reflect-get -- Preserve the receiver supplied to this proxy accessor.
return Reflect.get(target, key, receiver);
brix/explained-disables requires ESLint and Oxlint disable comments to use disable-line or
disable-next-line, name the affected rules, and include -- followed by a nonempty reason.
File-wide and unnamed disables are rejected, as is any directive naming brix/explained-disables.
Because such a directive could suppress the report on itself, files containing one report every
directive problem at line 1 with the offending line in the message. Unused disable directives are
errors as well. This checks the scope and presence of an explanation, not whether the explanation
is truthful. Keep vendored or generated files that start with a file-wide disable in
ignorePatterns instead.
Keep regression coverage for such exceptions. Avoid blanket file exclusions and comments that only claim an assertion or mock is safe. A deliberate project-wide rule change is supported, but turning off a managed rule globally should be rarer than a local, reasoned exception.
Oxfmt options and ignore patterns follow the same root-relative ownership model:
import { defineBrixOxfmtConfig } from "brix/config";
export default defineBrixOxfmtConfig({
singleQuote: true,
ignorePatterns: ["generated/**"],
});
Use the exact option names supported by the Brix-pinned Oxfmt version. Keep generated output ignored rather than formatting it by hand.
Configure a workspace at the root
#A workspace root owns .node-version, oxfmt.config.mts, oxlint.config.mts, local Oxc tools,
managed skills, and Git hooks. Members inherit them and should not contain generated copies. Put
shared decisions in the root configs and use workspace-relative globs for member-specific policy:
import { defineBrixOxlintConfig } from "brix/config";
export default defineBrixOxlintConfig({
overrides: [
{
files: ["apps/admin/src/**/*.ts", "apps/admin/src/**/*.tsx"],
rules: { "no-console": "error" },
},
{
files: ["packages/generated-contracts/src/**/*.ts"],
rules: { "brix/no-unknown-type-aliases": "off" },
},
],
});
Open the workspace root in the editor so it discovers the shared configs and binaries. Add a member
config only when a tool genuinely needs a separate boundary. A local config replaces ancestor
discovery; it does not automatically extend the root. Keep the Brix helper and explicitly compose
any root options the member must retain. Member brix init and workspace upgrades remove only
unchanged generated member configs and matching Node pins; customized files remain untouched.
Root workspace check, format, and verify apply Oxc only to root-owned files, then delegate member trees to their own phase scripts. A supported member config therefore remains authoritative for that member instead of being overridden by a second root-config pass. External applications keep their own formatting and checking scripts; missing external phase scripts are skipped.
Git hook policy likewise belongs only at the Git root under .brix-hooks/. brix hooks enable and
brix hooks disable control dispatch for the current clone. The standard pre-commit hook runs
brix staged against the exact index without rewriting unstaged work. The dispatcher skips a
policy file that is not executable; brix hooks status lists such policies and reports the
dispatcher as installed (N inactive hooks) rather than healthy until you run chmod +x on them.
Run and repair checks
#brix format
brix check
brix doctor
brix hooks status
brix staged
Format first, review the diff, and stage the intended result. brix check never applies formatter or
linter fixes. In a workspace, root commands cover all members; focused commands such as
brix check#checkout-bff select one project while still preparing its shared libraries. Hooks are
early feedback only—brix verify and CI remain authoritative.
Continue with project structure, testing, and workspaces.