What are Nx conformance rules and where do they fit next to ESLint?
Nx conformance rules are workspace-wide checks that run against the whole repository at once: the project graph, each project's configuration, the file layout, and metadata such as tags and owners. ESLint works at a different level. It parses source files one at a time, usually inside a single project's lint target. It can see imports and syntax, but it has no natural place to state "across all 300 projects, this must hold."
That is why some policies are awkward to write as lint rules. "Every project declares an owner" is a fact about project configuration, not about any file, so there is no source file for a lint rule to report on. "No app depends on another app" is a fact about graph edges. You can partly approximate it with import checks, but you would be inferring the edges from imports instead of reading the graph directly.
| Concern | ESLint | Conformance |
|---|---|---|
| Unit of analysis | Source file | Workspace or project |
| Typical inputs | AST, imports | Project graph, project config, tags, file layout |
| Example standard | No unused variables, hook rules | Owner declared, no app-to-app edges, required targets present |
| Judges code quality | Yes, partially | No |
Conformance checks structure: tags, ownership, dependency direction, and configuration shape. It does not judge code quality or runtime behavior. A project can pass every conformance rule and still be badly written.
Conformance has shipped as part of the paid Nx Powerpack and enterprise offerings, and its package name and licensing terms have changed over time. Check the official Nx documentation for the current package name, license requirement, and install steps before you adopt it.
+----------------------------------------------------------------------+
| Nx workspace (all projects) |
+----------------------------------------------------------------------+
| |
v v
+-----------------------------+ +-----------------------------------+
| ESLint (per file, per proj) | | Conformance (whole workspace) |
|-----------------------------| |-----------------------------------|
| input: one source file | | input: project graph, project |
| AST + imports | | config, tags, owners, |
| | | file layout |
| checks: unused vars, | | checks: owner declared, |
| hook rules | | no app -> app edges, |
| | | required targets present |
| reports on: a file + line | | reports on: a project / workspace |
+-----------------------------+ +-----------------------------------+
|
v
+----------------------------------------------------------------------+
| Not checked by conformance: code quality, runtime behavior |
+----------------------------------------------------------------------+
ESLint analyzes one source file at a time, while conformance reads the whole workspace (project graph, configuration, tags, owners and file layout) to enforce structural policies, and it does not judge code quality or runtime behavior.
How does the conformance configuration in nx.json work?
Conformance configuration lives under a conformance key in nx.json, as a list of rule entries. Each entry has four parts:
- Rule reference. A module path or package specifier that resolves to the rule implementation, either a built-in rule shipped with the conformance package or a local file in your workspace.
- Options. A rule-specific object. Each rule validates its own options, so a typo here usually surfaces as a configuration error.
- Project scoping. An optional list of projects, tags or patterns that limits where the rule applies. Without it, the rule covers every project. Scoping is how you apply a strict rule to new services while legacy code catches up.
- Status.
enforcedfails the check.evaluatedreports violations without failing.disabledturns the rule off but keeps it in the file, which preserves the intent and its options for later.
Field names and accepted values have shifted between releases. Check them against the JSON schema shipped with your installed version, and point your editor at that schema so mistakes show up while you type.
There are two ways to run the rules. nx conformance evaluates the rules and reports violations. Use it locally while you fix issues or tune options. nx conformance:check is the CI form: it exits non-zero only when an enforced rule has violations. Put it in the pipeline next to lint and type checks, before anything slow such as builds or end-to-end tests.
The output groups violations by rule, and each line names the offending project and a message. To trace a finding, start from the rule name to find the entry in nx.json, then use the project name to find the source. If the project should not be in scope at all, fix the scoping rather than the code.
{
"$schema": "./node_modules/nx/schemas/nx-schema.json",
"conformance": {
"rules": [
{
"rule": "@nx/conformance/enforce-project-boundaries",
"status": "enforced",
"options": {
"depConstraints": [
{
"sourceTag": "type:app",
"onlyDependOnLibsWithTags": ["type:feature", "type:util"]
}
]
}
},
{
"rule": "@nx/conformance/ensure-owners",
"status": "evaluated",
"projects": ["payments-*", "checkout-api"]
},
{
"rule": "./tools/conformance-rules/no-legacy-config",
"status": "disabled",
"projects": ["legacy-*"],
"options": { "allowList": ["legacy-billing"] }
}
]
}
}
A conformance block in nx.json with one enforced, one evaluated and one disabled rule, showing rule references, options and project scoping; verify field names against the schema shipped with your installed Nx version.
Which built-in rules should you start with, and do they replace ESLint module boundaries?
Begin with the project-boundaries rule. It covers the same ground most workspaces already address with tag-based module boundaries in ESLint: which projects may depend on which, based on tags such as scope: and type:. Since you already have that policy written down, it makes a good first rule. You can compare the conformance results with your existing lint output and see where they disagree.
Don't treat this article as the reference for which rules exist. Rule names and options change between releases, so check the rules exported by the conformance package installed in your workspace before you configure anything.
The key decision is ownership. If both ESLint and conformance enforce the same dependency constraints, you have two copies of one policy. Someone will update one and forget the other. After that, a change can pass lint and fail conformance, or the reverse, and engineers will start ignoring both. For each rule, write down which tool owns it.
| Mechanism | Strength | Weakness |
|---|---|---|
| ESLint module boundaries | Inline editor feedback, per-file precision | Only sees linted source files |
| Conformance rules | Workspace-wide view, project graph aware | No editor squiggles, extra licensing |
| CODEOWNERS | Routes changes to the right reviewers | Doesn't block bad dependencies |
| Custom CI scripts | Fully flexible | You maintain them forever |
| Code review | Catches intent and nuance | Inconsistent, doesn't scale |
Keep ESLint if your teams rely on fast editor feedback. Move boundaries to conformance if you need checks that span projects, or projects that ESLint doesn't lint. Run both only if they enforce different rules.
// eslint.config.mjs (workspace root)
// Ownership note: ESLint OWNS tag-based dependency constraints in this workspace.
// Do not duplicate these depConstraints in a conformance rule; if boundaries
// move to conformance later, delete this rule in the same change.
import nx from '@nx/eslint-plugin';
export default [
...nx.configs['flat/base'],
...nx.configs['flat/typescript'],
{
files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
rules: {
'@nx/enforce-module-boundaries': [
'error',
{
enforceBuildableLibDependency: true,
allow: [],
depConstraints: [
// Domain isolation: a scope may only use itself or shared code.
{ sourceTag: 'scope:orders', onlyDependOnLibsWithTags: ['scope:orders', 'scope:shared'] },
{ sourceTag: 'scope:billing', onlyDependOnLibsWithTags: ['scope:billing', 'scope:shared'] },
{ sourceTag: 'scope:shared', onlyDependOnLibsWithTags: ['scope:shared'] },
// Layering: apps -> feature -> ui/util, never upward.
{ sourceTag: 'type:app', onlyDependOnLibsWithTags: ['type:feature', 'type:ui', 'type:util'] },
{ sourceTag: 'type:feature', onlyDependOnLibsWithTags: ['type:feature', 'type:ui', 'type:util'] },
{ sourceTag: 'type:ui', onlyDependOnLibsWithTags: ['type:ui', 'type:util'] },
{ sourceTag: 'type:util', onlyDependOnLibsWithTags: ['type:util'] },
],
},
],
},
},
];
An existing ESLint module-boundaries setup with scope and type tag constraints, annotated to record that ESLint is the single owner of this policy so a conformance boundaries rule does not duplicate it.
How do you write and unit test a custom conformance rule?
A conformance rule is a function with metadata attached. You give it a name, a category and a description. The conformance runner calls its implementation with the workspace context, which includes the project graph and each project's configuration, plus any options set for the rule in nx.json. The implementation returns a list of violations. Each violation carries a message and the source project it belongs to, so the runner can attribute failures to a specific project instead of reporting a single workspace-wide failure.
A tag-requirement rule
The example rule takes a directory option, such as libs/. It visits every library node whose root sits under that directory. For each one, it checks that the tags include one scope:* entry and one type:* entry. If either is missing, the rule emits a violation for that project.
The message is where the rule pays off. A vague message like "Project is non-conformant" sends engineers to the platform team's channel asking for an exemption. An actionable message gets the fix done in the same pull request. A good message looks like this: "billing-data is missing a type:* tag. Add one to tags in libs/billing/data/project.json. To exempt, add the project to this rule's exclude list in nx.json with a justification."
Testing it
The tests don't need a real workspace. Hand-build a minimal project graph containing:
- one tagged library
- one library missing a
type:*tag - one application in the same directory
Call the implementation directly with that graph. Assert that exactly one violation comes back, that it names the untagged library, and that the application is ignored.
Custom rules are written against Nx-specific types and helpers, which may change between major versions. Pin your Nx version, and re-run these tests as part of every Nx upgrade.
// Core check, kept as a plain function so it can be unit tested
// without the Nx runner. Wrap it in your Nx version's rule helper.
type Node = { name: string; type: string; data: { root: string; tags?: string[] } };
type Graph = { nodes: Record<string, Node> };
export function checkTags(graph: Graph, opts: { directory: string; exclude?: string[] }) {
const violations: { message: string; sourceProject: string }[] = [];
for (const node of Object.values(graph.nodes)) {
// Only libraries under the configured directory, minus exemptions
if (node.type !== 'lib' || !node.data.root.startsWith(opts.directory)) continue;
if (opts.exclude?.includes(node.name)) continue;
const tags = node.data.tags ?? [];
for (const prefix of ['scope:', 'type:']) {
if (tags.some((t) => t.startsWith(prefix))) continue;
// Actionable message: project, expectation, fix, exemption path
violations.push({
sourceProject: node.name,
message: `${node.name} is missing a ${prefix}* tag. Add one to "tags" in ${node.data.root}/project.json. ` +
`To exempt, add it to this rule's "exclude" list in nx.json with a justification.`,
});
}
}
return violations;
}
// Unit test (Jest-style) against a hand-built minimal graph
test('flags only the library missing a type tag', () => {
const graph: Graph = { nodes: {
'billing-api': { name: 'billing-api', type: 'lib', data: { root: 'libs/billing/api', tags: ['scope:billing', 'type:feature'] } },
'billing-data': { name: 'billing-data', type: 'lib', data: { root: 'libs/billing/data', tags: ['scope:billing'] } },
'billing-app': { name: 'billing-app', type: 'app', data: { root: 'libs/billing/app' } },
} };
const result = checkTags(graph, { directory: 'libs/' });
expect(result).toHaveLength(1);
expect(result[0].sourceProject).toBe('billing-data');
expect(result[0].message).toContain('type:*');
});
A tag-requirement check that returns per-project violations with actionable messages, plus a unit test using a hand-built graph; wrap it in your Nx version's conformance rule helper.
How should you roll out conformance rules without breaking CI?
Roll out one rule at a time, and start every rule with status set to "evaluated". In that mode, violations are reported but the run does not fail, so you can merge the configuration without blocking anyone. Record the baseline violation count from the first run. It is the number you will work down, and it tells you whether the rule is realistic before anyone depends on it.
Next, reduce the count. You can fix violations directly, or narrow the rule's projects list so that legacy projects fall outside it. When a project is excluded, write down why, so a later reader knows the exemption was deliberate. A common pattern is to scope a new rule to a tag that your project generators add automatically. New projects then comply from their first commit, while older code is migrated on its own schedule. When the scoped set reports zero violations, change the status to "enforced" and let CI fail on regressions.
Track the exemption count next to the violation count. A rule that shows zero violations because thirty projects are excluded has been quietly hollowed out. The excluded projects are still out of standard, and the dashboard no longer shows it.
This sequence saves engineering time in two ways:
- Fewer review comments. Structural problems such as a misplaced dependency or a missing project field are caught by the tool, so reviewers stop flagging them by hand.
- Less CI noise. If you enforce a rule that fails on day one, teams learn to retry, skip, or ignore the job. Enforcing only clean rules keeps a red build meaningful.
Who should own the rules, and how are rule changes controlled?
Conformance only works if someone is accountable for it. In a multi-team monorepo, that is usually the platform team. It already owns the build, CI, and shared tooling, and it can see across project boundaries in a way that individual product teams cannot. In a single-team repository, a dedicated owner is often unnecessary. Whoever maintains nx.json can manage conformance alongside everything else.
Keep rules in one library and gate changes
Put custom rules in a dedicated workspace library, such as tools/conformance or libs/platform/conformance-rules, instead of scattering them across feature projects. This gives the rules a single test target and a clear dependency boundary. It also gives you one path to protect.
Add CODEOWNERS entries for nx.json and the rules library so the platform team must review any change to rule logic, severity, or project exclusions. Without that gate, a product team blocked by a failing check can switch the rule off for its own projects, and the standard quietly erodes one exclusion at a time.
Document the rationale next to the code
When a check fails, an engineer needs to know why the rule exists, not only what it flagged. Keep a short rationale in the rule's own source or a README beside it. It should cover the incident or constraint behind the rule, what a compliant fix looks like, and who to contact about exceptions. Link to that rationale from the violation message so the engineer lands on it directly.
Plan for the maintenance cost
A handful of rules is easy to maintain. A few dozen custom rules become an internal product, with its own support load and documentation debt, and the platform team should staff it that way.
When should you avoid Nx conformance, and what does it cost?
Conformance is a commercial feature, and its packaging and licensing have changed before. Budget for the license, and for the chance that the terms change again. Every custom rule is written against the conformance API, so each one adds to the cost of leaving. Custom rules also depend on Nx's project graph and plugin APIs, which means a major Nx upgrade can require rule fixes before the upgrade itself can merge.
Runtime is the other recurring cost. Measure it in your own pipeline. A rough model helps you decide whether to run checks on every PR or only on a schedule:
Illustrative estimate (assumed numbers, not a benchmark): check time ≈ rules × projects × average cost per project check Assuming 15 rules, 800 projects and 5 ms per check: 15 × 800 × 5 ms = 60 s per run, before project graph computation.
Structural rules also create friction. Conventions such as "no app imports another app" have legitimate exceptions, and every exemption needs a recorded reason. A rule switched to error mode can block a PR that never touched the code it flags. Most importantly, a green conformance run only proves the workspace has the right structure. It says nothing about code quality or runtime behavior, so review and testing still carry that load.
| Situation | Adopt conformance? | Why |
|---|---|---|
| Small workspace, few projects | No | Conventions fit in reviewers' heads |
| Single-team repo | No | Rules duplicate what the team already agrees on |
| ESLint boundaries plus CODEOWNERS cover your needs | No | Adds a license and upgrade work for little extra coverage |
| Many teams, drifting project standards | Yes | Central, measurable workspace governance pays off |
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nx conformance rules, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.