What are Nx conformance rules and what do they check that ESLint does not?

Nx conformance rules are checks that run against the whole workspace rather than against individual source files. A rule receives the project graph and the project configurations, then reports violations at the project or workspace level. That is the right place to ask questions like "does every backend service declare an owner?", "does every deployable app define the targets our pipeline expects?", or "do any projects depend on things they shouldn't?"

ESLint works file by file. It parses a module, walks its syntax tree, and reports problems in that file. Nx's module boundary lint rule extends this with project tags, but it is still triggered by import statements in source files. It cannot see a missing test target, an app with no owner, or a project that sits outside the agreed folder layout, because none of those show up in a single file's imports.

Concern ESLint (incl. tag-based boundaries) Nx conformance
Unit of analysis One source file at a time Project graph and project config
Typical findings Unsafe patterns, disallowed imports Missing owners, required targets, structural drift
Triggered by Code being linted Workspace state as a whole

The two are complementary. Keep ESLint for code-level correctness and import rules. Use conformance for organisational standards that only make sense across projects.

Conformance is an Nx Powerpack feature. It ships as an Nx plugin and requires a license. Packaging and licensing terms have changed over time, so check the current Nx documentation before you plan a rollout.

How do Nx conformance rules work?

Conformance rules are declared in one place, the workspace-level Nx configuration, rather than in each project. That placement is deliberate. A standard that every backend service must meet should not depend on each team remembering to opt in.

Conceptually, each rule entry has four parts:

  • A rule reference. This points to the implementation, which can be a built-in rule from the conformance plugin or a local file in your workspace.
  • Options. These parameterize the rule, such as allowed dependency tags or a required target name.
  • A project scope. This limits the rule to a subset of projects, for example only projects tagged as backend services.
  • A status. This controls what a violation does.

Treat these labels as a sketch of the model, not the schema. Verify the exact field names and structure against the current Nx documentation before writing any configuration.

At run time, the runner builds the project graph. It then calls each rule with context that includes the graph, project configurations and the rule's options. Each rule returns violations, and the runner collects them into a single report. Because rules share one graph computation, adding a rule does not add a second pass over the workspace.

Status levels let you separate signal from enforcement. An enforced rule fails the check and can block a merge. A lower level reports findings without failing, which suits a rule you are still evaluating. You can also disable a rule without deleting its configuration. Confirm the exact level names in the docs.

Rules see what is declared: project configuration, tags, targets, file contents and graph edges. They never run your services. They cannot catch a missing timeout or a leaked connection at runtime. They can only check that the configuration meant to prevent such problems exists.

// nx.json (excerpt). Conceptual sketch only: verify every field name,
// rule ID and status value against the current Nx conformance docs.
{
  "conformance": {
    "rules": [
      {
        // Built-in rule from the conformance plugin.
        "rule": "@nx/conformance/enforce-project-boundaries",
        // Violations fail the check and can block a merge.
        "status": "enforced",
        // Scope: only projects tagged as backend services.
        "projects": ["tag:type:backend-service"]
      },
      {
        // Local rule implemented in this workspace.
        "rule": "./tools/conformance/require-health-target.ts",
        // Options parameterize the rule. Here, the target every service must declare.
        "options": { "targetName": "health-check" },
        // Report findings without failing while the team evaluates the rule.
        "status": "evaluated",
        "projects": ["tag:type:backend-service"]
      },
      {
        // Keep the configuration but switch the rule off.
        "rule": "./tools/conformance/no-shared-db-client.ts",
        "status": "disabled"
      }
    ]
  }
}

A conceptual nx.json sketch of three conformance rule entries, each with a rule reference, options, a project scope and a status level. Field names and values are illustrative and must be checked against current Nx documentation.

Which backend rules are worth enforcing first?

That limit decides which rules come first. Some project configuration maps directly to an operational question: who gets paged when this service breaks, what does it depend on, and how is it built and shipped. Rules that answer those questions are worth enforcing early. Each one below is a predicate over the project graph or project configuration.

  • Every deployable service declares an owner. For every project tagged as a deployable app, an owner field or an owner:* tag must be present and non-empty.
  • Services do not import other services' internal libraries. For every dependency edge from project A to project B, if B is marked internal to a service scope, A must belong to that same scope.
  • Every app defines a consistent target set. For every application project, build, test, lint, and either container or deploy must exist.
Rule Risk it reduces Suggested starting status
Deployable service declares an owner Incidents with no responder; orphaned services nobody upgrades Enforced once existing gaps are filled
No imports from another service's internal libs Hidden coupling that forces two services to be deployed together Evaluated (report-only), then enforced
Consistent app target set CI and release tooling silently skipping a service Evaluated, then enforced

Naming conventions and folder layout can wait. A badly named library rarely causes an outage, but a rule against it fails builds, generates exemption requests, and teaches teams that conformance is noise. That cost lands most heavily on the rules that do matter. Spend that tolerance on the rules that prevent real failures.

How do you write a custom conformance rule?

A custom rule is a module that exports a rule definition: a name, a category, a description, and an implementation function. The implementation receives context about the workspace, including the project graph, any options configured for the rule, and the set of projects it applies to. It returns a list of violations, each with a message and a reference to the offending project or file. Conceptually, it loops over the projects, filters to the ones in scope (for example, those tagged type:backend), checks a condition, and collects a violation for each failure. Treat this as the shape, not the signature. The exact factory function, context fields, and violation format belong to Nx Powerpack and can change, so confirm them in the current Nx docs before writing code.

Write messages for the team that will read them

A violation message will most often be read by someone who has never heard of the rule. Name the project, state what was expected and what was found, and say how to fix it or where to request an exemption. "Project billing-api has no health target; add one using the service generator" leads to a fix. "Invalid configuration" leads to a support ticket.

Test against fixture graphs

Build small, hand-written project graphs that cover a compliant project, a violating one, an out-of-scope one, and edge cases like missing tags. Assert on the exact violations returned. A rule runs against every project in the workspace, so a bug in it can fail CI for every team at the same moment. Tests are cheaper than that outage.

// Conceptual shape only. The real factory, context fields and violation
// format come from Nx Powerpack; check current Nx docs before using.
type Violation = { message: string; sourceProject: string; file?: string };

export const requireHealthTarget = {
  name: 'require-health-target',
  category: 'reliability',
  description: 'Backend services must expose a health target.',
  implementation(context: RuleContext): Violation[] {
    const violations: Violation[] = [];
    for (const project of Object.values(context.projectGraph.nodes)) {
      // Scope: only projects tagged as backend services.
      const tags = project.data.tags ?? [];
      if (!tags.includes('type:backend')) continue;
      if (!project.data.targets?.health) {
        violations.push({
          sourceProject: project.name,
          // Actionable: what, where, how to fix, where to ask.
          message: `Project '${project.name}' has no 'health' target. ` +
            `Add one with the service generator, or request an exemption ` +
            `from the platform team.`,
        });
      }
    }
    return violations;
  },
};

// Unit test against a hand-written fixture graph (test-runner agnostic).
const fixture = { projectGraph: { nodes: {
  ok:      { name: 'orders-api',  data: { tags: ['type:backend'], targets: { health: {} } } },
  bad:     { name: 'billing-api', data: { tags: ['type:backend'], targets: {} } },
  ignored: { name: 'web-ui',      data: { tags: ['type:frontend'], targets: {} } },
  untagged:{ name: 'scripts',     data: { targets: {} } },
} } } as unknown as RuleContext;

const result = requireHealthTarget.implementation(fixture);
console.assert(result.length === 1 && result[0].sourceProject === 'billing-api');

Pseudocode-style custom rule that flags backend projects missing a health target with an actionable message, plus a fixture-graph test; real Nx Powerpack signatures must be confirmed in the docs.

Running conformance locally and in CI

Run conformance as its own CI step rather than folding it into lint or test. A separate step gives a separate pass/fail signal: when it goes red, the failure points at workspace standards, not at a broken unit test or a style nit. It also lets you schedule the check independently. For example, you can run it on every pull request but skip it for documentation-only changes.

How results map to pass or fail

The step's exit status follows each rule's configured status. Violations from enforced rules fail the step. Findings from report-only rules appear in the output but leave the step green. This split is what makes gradual rollout work: a new rule can show the size of its backlog in every CI run without blocking anyone's merge.

Local and CI invocation

Locally, engineers run the conformance check through the Nx CLI before pushing. In CI, the step runs the same check after dependencies are installed and the workspace is available. Nx Powerpack's command names and flags have changed between releases, so confirm the exact command in the current Nx documentation rather than copying it from an older pipeline.

Cost and ownership

Expect added CI time. Rules evaluate the whole workspace, so the cost grows with the number of projects. Measure it in your own pipeline before you decide where the step runs.

Name a specific owner for the conformance step, either a person or a platform rotation. That owner triages red runs, decides whether the cause is a real violation or a rule bug, and responds quickly. Without one, teams start retrying the step, marking it optional, or adding blanket exemptions to get unblocked, and the check stops enforcing anything.

#!/usr/bin/env bash
# ci/conformance.sh: runs workspace conformance as its own CI step,
# separate from the lint and test steps, so a red result points at standards.
#
# Local use (before pushing):  ./ci/conformance.sh
# CI use: call this as a dedicated step after dependencies are installed.
set -euo pipefail

# Command names have changed between Nx Powerpack releases.
# Confirm the current command in the Nx docs and override it here if needed.
CONFORMANCE_CMD="${CONFORMANCE_CMD:-npx nx conformance:check}"

# Base branch for the changed-files check. In CI, set this to the PR target.
BASE_REF="${BASE_REF:-origin/main}"

# Skip pull requests that change only documentation.
if git rev-parse --verify --quiet "$BASE_REF" >/dev/null; then
  changed="$(git diff --name-only "$BASE_REF"...HEAD)"
  if [ -n "$changed" ] && ! printf '%s\n' "$changed" | grep -qvE '(\.md$|^docs/)'; then
    echo "Docs-only change; skipping conformance."
    exit 0
  fi
fi

# The step's exit status is the check's exit status:
# - violations from enforced rules give a non-zero exit, so the step fails
# - findings from report-only rules are printed but still exit 0
# Do not add '|| true' or retries here. A red step goes to the named owner.
echo "Running: $CONFORMANCE_CMD"
start=$(date +%s)
set +e
$CONFORMANCE_CMD
status=$?
set -e
echo "Conformance finished in $(( $(date +%s) - start ))s (exit $status)"

# Record the duration so you can track the CI time this step adds.
exit "$status"

This wrapper script runs conformance as a dedicated step both locally and in CI, skips docs-only changes, and passes the check's exit code through unchanged so enforced violations fail the step and report-only findings do not; confirm the conformance command name in the current Nx docs.

When should you roll out a rule, and how do you keep exemptions honest?

Start with one or two rules, not ten. Configure each in report-only (non-blocking) mode so it runs on every pipeline without failing builds, then publish the resulting violation list where owning teams can see it, grouped by project. That list becomes the work queue: each project either fixes its violations or gets an explicit exemption. Once the list is empty apart from documented exemptions, promote the rule to enforced. Only then add the next rule.

Enforcing on day one fails predictably. A new rule run against a mature workspace surfaces every historical shortcut at once, and teams that did nothing wrong today find their merges blocked. The fastest way out is a wildcard exclusion, and a rule that excludes half the workspace no longer describes a standard.

Exemption hygiene

  • Name projects precisely. Exclude specific projects, or selectors as narrow as a single tag, rather than patterns like *-api. A broad pattern silently exempts every future project that happens to match.
  • Record the reason. Each exclusion should carry a comment with the owner, the reason, and the condition for removal, such as "legacy auth service, scheduled for decommission."
  • Review on a schedule. Revisit exclusions quarterly. Remove entries that no longer apply, and treat anything still exempt after two reviews as a decision to escalate.

This costs a little up front, but it replaces recurring reviewer attention and periodic cleanup sprints with a check that runs on every change. Violations get caught at the pull request instead of being rediscovered months later.

{
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/enforce-project-boundaries",
        "status": "enforced",
        "projects": [
          "*",
          {
            "matcher": "!legacy-auth-service",
            "explanation": "Owner: platform-team. Legacy auth service, scheduled for decommission. Remove this exclusion once the service is deleted. Last reviewed: 2026-Q4."
          }
        ]
      },
      {
        "rule": "@nx/conformance/ensure-owners",
        "status": "evaluated"
      }
    ]
  }
}

An nx.json conformance block with one rule enforced and one exempted project, named exactly and documented, while a second rule stays in evaluated (report-only) mode until its violation list is cleared.

When should you avoid Nx conformance, and what are the alternatives?

Conformance is a paid Powerpack feature, so the license is a recurring cost. Every custom rule is also code your platform team owns. When generators, project layouts or config conventions change, rules need updating, or they start producing false positives that people learn to ignore.

A small workspace, with a handful of backend apps and one team, often gets most of the value from tools it already has:

Approach Cost Scope Maintenance Enforcement strength
Nx conformance Powerpack license plus rule authoring Whole workspace, project graph and file contents Ongoing for custom rules Strong: fails CI, with tracked exemptions
Custom ESLint rules Free Per-file source code Moderate, coupled to linter APIs Strong within linted files, blind to project config
Tag-based module boundaries Free, built into Nx linting Import relationships between projects Low, but tags drift without review Strong for dependency direction only
CODEOWNERS-style ownership Free Paths in the repository Low Social: requires a review, not compliance
Scripts over the project graph Free Anything exposed by nx graph output High, as ad hoc code without a framework As strong as the CI step that runs them

Conformance becomes worth the cost when you have many teams, many projects, and standards that cross files and project configuration, where ad hoc scripts would turn into an unmaintained framework of their own.

It does not replace integration tests or deployment checks. A project can pass every rule and still fail against a real database or a misconfigured environment.

Powerpack features and configuration keys have changed over time. Check current Nx documentation before you adopt it or upgrade.

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.