What is Nx conformance and how does it differ from lint rules?

Nx conformance is a set of checks that run against the whole workspace at once. It evaluates the project graph and project metadata, such as tags, configuration, and the dependency edges between projects. ESLint works differently: it parses one source file at a time and reports problems at specific lines. That difference determines what each tool can enforce. A lint rule can catch an unsafe import in a file. It cannot tell you that a service project has no declared owner, or that someone added a build target the platform team has banned.

Module-boundary lint sits between the two. It uses project tags to decide which imports are allowed, but it still runs through ESLint, file by file, and only sees dependencies that appear as imports. Conformance treats the graph itself as the input.

Concern Per-file ESLint Module-boundary lint Nx conformance
Unit of analysis Source file Imports, checked against tags Project graph and metadata
Required ownership metadata No No Yes
Allowed dependency direction between layers (e.g. domain must not depend on transport) No Yes, for imports Yes, across the graph
Banned project configurations No No Yes

Conformance ships as part of Nx Powerpack, a licensed add-on that is separate from open-source Nx core. Nx's licensing and packaging have changed over time, so check the official docs for your Nx version to confirm current terms, package names, and supported commands.

Conformance is aimed at platform and backend engineers who run multi-team monorepos. In that setting, standards drift because no single reviewer sees every project, so the checks need to cover the workspace as a whole.

+--------------------+    +--------------------+    +--------------------+
|   Source files     |    |  Imports in files  |    |   Project graph    |
|  (one at a time)   |    |  + project tags    |    |  + project.json /  |
+---------+----------+    +---------+----------+    |  tags / targets /  |
          |                         |               |  owners metadata   |
          v                         v               +---------+----------+
+--------------------+    +--------------------+              |
|  Per-file ESLint   |    | Module-boundary    |              v
|  rules             |    | lint (via ESLint)  |    +--------------------+
+---------+----------+    +---------+----------+    |  Nx conformance    |
          |                         |               |  (Nx Powerpack)    |
          v                         v               +---------+----------+
+--------------------+    +--------------------+              |
| Findings at a      |    | Disallowed import  |              v
| file + line        |    | between tagged     |    +--------------------+
|                    |    | projects           |    | Workspace findings |
+--------------------+    +--------------------+    | - missing owner    |
                                                    | - domain->transport|
                                                    | - banned target    |
                                                    +--------------------+

Per-file ESLint reads one source file at a time and module-boundary lint checks imports against project tags, while Nx conformance takes the whole project graph and its metadata as input and reports workspace-level violations such as missing owners, disallowed layer dependencies and banned targets.

How should you design project tags before writing workspace rules?

Most conformance and module boundary rules don't inspect your code structure directly. They read project tags. A rule like "services may not import other services" only works if every service is tagged as one. Tags therefore define what your rules can express, and the taxonomy should exist before the rules do.

A taxonomy that works well for backend monorepos uses three independent dimensions:

Dimension Example values What rules use it for
type service, data-access, domain, util Layering: a util must not depend on data-access, and a domain must not import a service
scope billing, identity, shared Ownership and bounded contexts: billing may depend only on billing and shared
runtime node, worker Platform constraints: a worker must not pull in HTTP server dependencies

Keep the dimensions independent so each rule can target one concern. In project.json, a billing API carries all three tags: "tags": ["type:service", "scope:billing", "runtime:node"]. Use a key:value prefix so rules can match on the dimension without listing every value.

Inconsistent tagging undermines every rule built on it. A project tagged type:svc instead of type:service silently escapes a rule, which is a false negative. A project with no scope tag can trip a rule that requires one, which is a false positive. Teams learn quickly to ignore a noisy gate, and that habit outlasts the cleanup.

Audit and normalize tags before you write any rule. List every project's tags, merge spelling variants, fill in missing dimensions, and get each owning team to agree on its assignments.

// tools/audit-tags.ts: report projects whose tags don't match the taxonomy.
// Run this before writing any rule, and fix what it reports first.
import { createProjectGraphAsync } from '@nx/devkit';

// Canonical taxonomy: each project needs exactly one value per dimension.
const allowed: Record<string, string[]> = {
  type: ['service', 'data-access', 'domain', 'util'],
  scope: ['billing', 'identity', 'shared'],
  runtime: ['node', 'worker'],
};

async function main() {
  const graph = await createProjectGraphAsync();
  const problems: string[] = [];

  for (const [name, node] of Object.entries(graph.nodes)) {
    const tags = node.data.tags ?? [];

    for (const [dim, values] of Object.entries(allowed)) {
      const matches = tags.filter((t) => t.startsWith(`${dim}:`));
      // A missing dimension will later cause false positives.
      if (matches.length !== 1) {
        problems.push(`${name}: expected one ${dim}:* tag, found ${matches.length}`);
        continue;
      }
      // A misspelled value (e.g. type:svc) would silently escape rules.
      const value = matches[0].slice(dim.length + 1);
      if (!values.includes(value)) {
        problems.push(`${name}: unknown ${dim} value "${value}"`);
      }
    }

    // Tags outside the taxonomy usually mean a typo or a legacy convention.
    for (const t of tags) {
      if (!t.includes(':') || !(t.split(':')[0] in allowed)) {
        problems.push(`${name}: unrecognized tag "${t}"`);
      }
    }
  }

  problems.forEach((p) => console.log(p));
  process.exitCode = problems.length > 0 ? 1 : 0;
}

main();

A tag audit script reads the Nx project graph and flags missing dimensions, misspelled values and unrecognized tags, so you can normalize tags before any rule depends on them.

Which conformance rules should backend teams start with?

Four rules cover most of the structural risk in a backend workspace. Each one exists because a specific failure mode is expensive to debug after it ships.

Rule What it blocks Operational risk it prevents
No direct service-to-service dependencies A project tagged type:service importing another service Coupled deploys and runtime contracts that exist only as imports, with no versioned API
Domain libraries stay framework-free type:domain importing type:infra, ORM, HTTP, or messaging code Business logic that can't be unit tested without a database, or moved to another runtime
Every project declares an owner Projects with no owning team in metadata Incidents and dependency upgrades with nobody accountable
Deprecated libraries gain no new dependents New edges into projects tagged status:deprecated Migrations that never finish because the old library keeps acquiring consumers

The service rule matters most. When one service imports another, the build graph treats them as a single unit. A change in one triggers rebuilds and redeploys of both, and the contract between them can't be versioned or monitored. Shared behavior belongs in a library or behind a network API.

The deprecation rule is cheap to add. It freezes the current dependents, so the migration has a fixed scope that can only get smaller.

Every rule should name the incident or cost it prevents. Record that reason next to the rule's configuration, and review it when the risk no longer applies. Avoid rules that encode preference, such as folder naming or file layout. Teams will route around them, and the workarounds weaken trust in the rules that do protect production.

How do you configure and run conformance rules locally and in CI?

Conformance configuration lives centrally in the workspace configuration, typically nx.json, rather than in each project. That placement is deliberate: platform engineers own the rule set in one reviewable file, and teams cannot quietly opt out by editing their own project config. Each rule entry names the rule, sets its status (for example, whether a violation fails the run or only reports), passes rule-specific options, and optionally lists the projects it applies to. Scoping by project pattern or tag lets you apply a rule such as "services must not import frontend libraries" only to projects tagged type:service, without generating noise elsewhere. Illustrative: confirm the exact key names, status values, and matcher syntax against the schema of your installed Nx and Powerpack versions.

Locally, engineers run conformance through the Nx CLI. Depending on your version, this may be a single command or a pair that separates checking from applying fixes. In CI, use the non-mutating check form so the pipeline reports violations instead of rewriting files. Illustrative: check nx --help for the command names your installation provides.

The main CI decision is scope. Running every rule on every change gives a complete picture and catches violations introduced indirectly, such as a new dependency edge that breaks a boundary rule elsewhere. Restricting checks to affected projects is cheaper, but it can miss workspace-wide rules, and depending on your version, conformance may evaluate the whole graph regardless. Measure the actual cost on your own graph by timing a full run on a representative branch. Do not assume the cost is negligible.

// nx.json (excerpt). ILLUSTRATIVE: verify key names, status values and
// matcher syntax against the schema of your installed Nx / conformance plugin.
// Nx parses nx.json as JSONC, so comments are allowed here.
{
  "conformance": {
    "rules": [
      {
        // Boundary rule: services must never depend on frontend libraries.
        "rule": "@nx/conformance/enforce-project-boundaries",
        // "enforced" fails the run; "evaluated" only reports (useful during rollout).
        "status": "enforced",
        // Scope the rule to backend services only, to avoid noise elsewhere.
        "projects": ["tag:type:service"],
        "options": {
          "depConstraints": [
            {
              "sourceTag": "type:service",
              "notDependOnLibsWithTags": ["type:frontend"]
            }
          ]
        }
      },
      {
        // Start new rules in report-only mode, then promote to "enforced".
        "rule": "@nx/conformance/ensure-owners",
        "status": "evaluated"
      }
    ]
  }
}

// Commands (ILLUSTRATIVE; confirm with `nx --help`):
//   Local, may apply fixes:   npx nx conformance
//   CI, check only:           npx nx conformance:check
//   Measure CI cost on your graph before deciding scope:
//                             time npx nx conformance:check

Illustrative nx.json excerpt showing centrally configured conformance rules (one enforced and scoped to type:service projects, one report-only), followed by the local, CI and timing commands to verify against your installed version.

How do you roll out a new rule without blocking every team?

Introduce every new rule in three phases, and do not skip the first.

Phase 1: Report, don't block

Add the rule with a non-blocking status so that violations are reported but the run still passes. The exact status names depend on your version, so check them before you commit the config. Run it against the main branch and record the result: how many violations there are, which projects have them, and which teams own those projects. That count tells you whether the rule can be fixed in a week or will take a quarter.

Phase 2: Fix or exempt explicitly

Fix the cheap violations directly, ideally in small pull requests that the owning team reviews. For the rest, add an explicit exemption scoped to the specific project. Give each exemption an owner and a removal plan, such as a tracking ticket or a target date. An exemption without an owner is a permanent exception.

Phase 3: Promote to blocking

Once the exemption list stops growing, switch the rule to blocking in CI. From then on, the rule only stops new violations.

What goes wrong if you skip Phase 1

If a rule blocks on day one, CI fails for every team that has an existing violation. Their pull requests stall even when the change has nothing to do with the rule. Under that pressure, teams add blanket exemptions to get unblocked, and nobody removes them. Engineers learn that governance means busywork, and later rules get the same treatment.

Make every rule's error message link to an internal doc that explains why the rule exists and how to fix a violation. A failure that explains itself gets fixed. One that doesn't usually gets exempted.

How do you write a custom conformance rule?

A custom rule is a function the conformance runner calls with a read-only view of the workspace: the project graph, each project's configuration and tags, and the dependency edges between projects. The rule checks one condition and returns a list of violations. Each violation names the project that broke the rule and carries a message telling the owner what to change. A rule that only says "something is wrong somewhere" is useless to the team on the receiving end.

The shape looks roughly like this. This is a sketch of the logic, not the exact Nx API. Check the conformance documentation for your installed version before writing real code.

  • Input: project graph, project configurations, rule options (for example, an allowed list of database drivers)
  • For each project tagged type:service:
    • collect its external dependencies from the graph
    • if any dependency is not in the allowed list, record a violation with the project name, the offending package and a link to the internal doc
  • Return the violations and a status: passed or failed

Keep rules small and testable

Give each rule one concern. A rule that checks drivers, logging and ports at once produces messages nobody can act on, and you cannot turn off one check without losing the others.

Make rules deterministic. They should never read the network, the clock or the local environment. The same graph should always produce the same result on a laptop and in CI.

Version rules like any shared library. Unit-test them against small fixture graphs that cover passing, failing and edge cases.

Budget for maintenance

Budget for upkeep. Custom rules depend on project-graph structures that Nx can change between releases. When an upgrade alters those internals, your rules break, and the platform team has to fix them before anyone can upgrade Nx. Keep custom rules few and isolate graph access behind a thin helper so that one fix covers every rule.

// Rule logic as a pure function over plain data. A thin adapter (not shown)
// maps your Nx version's rule API onto these types, so an Nx upgrade means
// fixing one adapter instead of every rule.
import assert from 'node:assert/strict';

interface ProjectView { name: string; tags: string[]; externalDeps: string[] }
interface Violation { project: string; message: string }
interface Options { allowedDrivers: string[]; driverPackages: string[]; docPath: string }

export function checkDatabaseDrivers(projects: ProjectView[], opts: Options) {
  const violations: Violation[] = [];
  for (const p of projects) {
    if (!p.tags.includes('type:service')) continue; // one concern: services only
    for (const dep of p.externalDeps) {
      // Only judge packages that are database drivers; ignore everything else.
      if (opts.driverPackages.includes(dep) && !opts.allowedDrivers.includes(dep)) {
        violations.push({
          project: p.name,
          message: `Uses unapproved driver "${dep}". Switch to one of: ` +
            `${opts.allowedDrivers.join(', ')}. See ${opts.docPath}`,
        });
      }
    }
  }
  // Deterministic: no network, clock or env reads; same input, same output.
  return { status: violations.length ? 'failed' : 'passed', violations };
}

// Fixture-based unit test: small graph covering pass, fail and an ignored lib.
const opts = { allowedDrivers: ['pg'], driverPackages: ['pg', 'mysql2'], docPath: 'docs/platform/db-drivers.md' };
const result = checkDatabaseDrivers([
  { name: 'orders-api', tags: ['type:service'], externalDeps: ['pg', 'zod'] },
  { name: 'billing-api', tags: ['type:service'], externalDeps: ['mysql2'] },
  { name: 'shared-utils', tags: ['type:lib'], externalDeps: ['mysql2'] },
], opts);
assert.equal(result.status, 'failed');
assert.deepEqual(result.violations.map((v) => v.project), ['billing-api']);

A conformance rule's core logic written as a small, deterministic pure function with a fixture-based test, kept separate from the Nx-specific rule API so upgrades only touch a thin adapter.

What are the alternatives to Nx conformance, and when should you avoid it?

Conformance is one tool among several, and each handles a different kind of problem. Generators prevent violations when a project is created. Conformance catches drift that builds up afterwards. Human review handles the judgment calls that no rule can encode.

Mechanism Best at Weak at
Generators Correct defaults at creation time Projects that change after scaffolding
Module-boundary lint rule Import constraints between tagged projects Rules about config, metadata, or file layout
Conformance Workspace-wide drift on project config and structure Portability, and it requires a license
Scripts over the project graph Small, one-off checks Reporting, exemptions, and gradual rollout
CODEOWNERS review Design and judgment Repetitive mechanical checks
CI gates Blocking merges on any of the above Explaining why a check failed

Give each concern one owner. If both a lint rule and a conformance rule check imports, a single violation fails CI twice, and the two checks will eventually disagree.

Avoid conformance when you can't justify the Nx Powerpack license, or when there is a realistic chance you will leave Nx. Rules written against the Nx project graph don't move with you, so your governance logic becomes vendor-coupled. A check of only a few lines, such as "every service has a README", is cheaper to maintain as a plain script.

A well-scoped rule set replaces review comments that reviewers would otherwise repeat on every pull request, and it surfaces drift before that drift spreads across dozens of projects. Each rule still has a development and upgrade cost, so add one only when it pays for itself.

The platform team owns and maintains the rules. Changes go through a short written proposal that backend teams can comment on before a rule moves to error severity. That keeps the rules accountable to the people they affect, so governance does not drift into bureaucracy.

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, 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.