| name | repo-architecture |
| description | Cross-cutting architecture reference for the eslint-plugin-boundaries monorepo — the dependency graph between packages, the Nx target graph, and the release flow. Load before designing or reviewing anything that spans more than one project. |
eslint-plugin-boundaries repository architecture
This is a pnpm + Nx monorepo publishing @boundaries/elements, @boundaries/eslint-plugin, and the jsboundaries.dev documentation website. Its architecture is defined by each project's AGENTS.md plus this cross-cutting reference, not by convention alone.
Where the rules live
<project>/AGENTS.md is the source of truth for that project — every packages/*, examples/*, support/*, and test/* directory. Read the one(s) touching the area before making a judgment call.- Per-file conventions live in
.agents/rules/[rule-name].md. Read them when you need to know what's expected in a given file type — e.g. .agents/rules/eslint-rule-authoring.md when adding a rule to eslint-plugin.
packages/eslint-plugin/eslint.config.mjs and packages/elements/eslint.config.mjs are where each package's internal layering becomes mechanically enforced (both dogfood eslint-plugin-boundaries on themselves) — treat them as ground truth over any prose description when the two disagree.- Long-form reference docs (per-rule documentation, ADRs) live in
docs/ and packages/website/docs/ — non-normative companions: rules/skills win on disagreement.
Component map
| Directory | Nx project | Publishes | Role |
|---|
packages/elements | elements | @boundaries/elements | Element descriptors and matchers — the classification engine eslint-plugin builds rules on |
packages/eslint-plugin | eslint-plugin | @boundaries/eslint-plugin | The ESLint plugin itself: rules, settings parsing, messages |
packages/website | website | (deployed, not published) | Docusaurus site for jsboundaries.dev; version kept in lockstep with eslint-plugin |
examples/typescript | example-typescript | (not published) | Minimal TypeScript project consuming the plugin, built against current source |
examples/oxlint-integration | example-oxlint-integration | (not published) | Demonstrates pairing the plugin with Oxlint |
support/eslint-config | eslint-config | @boundaries/repo-eslint-config | Shared ESLint flat config every project's eslint.config.* composes |
support/cspell-config | cspell-config | @boundaries/repo-cspell-config | Shared cspell config every project's cspell.config.* composes |
test/eslint-plugin-e2e | eslint-plugin-e2e | (not published) | Plain-Node end-to-end suite against the built plugin |
Dependency graph and direction
elements has no in-repo dependencies. eslint-plugin depends on it for classification. eslint-plugin-e2e and both examples/* depend on the built eslint-plugin (via Nx's dependsOn: ["build"] / ["^build"], not a published version).support/eslint-config and support/cspell-config are depended on by every project via implicitDependencies in each project.json, and via each project's own lint/check:spell target depending on that support package's eslint:config/cspell:config target.website is downstream of eslint-plugin conceptually (it documents the plugin's current API and versions its docs alongside plugin releases) but has no Nx build dependency on it — keep packages/website/docs/rules/ in sync with eslint-plugin changes manually.- Run
pnpm nx graph to see the live dependency graph rather than trusting this table if it's unclear whether it's stale.
Nx target graph
Standardized target names (lint, check:types, check:spell, build, test:unit, test:mutation, test:e2e, check:all) are defined with common defaults in nx.json's targetDefaults, and overridden per-project in project.json only where a project's needs diverge — see .agents/rules/nx-project-config.md for what that override mechanism looks like and why it matters for caching.
The one non-obvious edge: eslint-plugin and elements both make their own lint target depend on build, because each dogfoods its own compiled output (eslint-local-rules.js requires ./dist/index.js) to lint its own source. A stale dist/ means a lint run's boundary checks are stale too — Nx handles this automatically via the dependsOn, but be aware of it when reasoning about why a lint result did or didn't change.
Release flow
Each package is versioned independently under semver — see .agents/rules/changelog-and-versioning.md. At a high level: release is the default PR base branch (PRs squash-merge into it); a maintainer periodically opens a PR from release to main (merge-commit strategy) to cut a release, tags each modified package as <package-name>-vX.Y.Z, and publication to npm happens automatically once a GitHub release is created. Full detail lives in .github/CONTRIBUTING.md.
Known inconsistency, not yet resolved: .github/CONTRIBUTING.md and nx.json's defaultBase disagree on the stable branch name (main vs master), and README.md/.github/PULL_REQUEST_TEMPLATE.md mostly link via master. Don't silently pick one when it matters — flag it.
