Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt

Use this file to discover all available pages before exploring further.

Boundaries enforce import direction between architectural zones. A zone groups files by glob pattern; a rule declares which zones may import from which. Violations appear as boundary-violation issues in fallow dead-code output. For preset descriptions, output formats, and suppression, see Architecture boundaries.

​
Presets

Fallow ships four built-in presets for common architecture patterns:
PresetZonesDescription
layered4Classic N-tier: presentation, application, domain, infrastructure
hexagonal3Ports and adapters: adapters, ports, domain
feature-sliced6Feature-Sliced Design: strict downward-only imports
bulletproof4Bulletproof React: app, features, shared, server
{
  "boundaries": {
    "preset": "bulletproof"
  }
}
See Architecture boundaries - Presets for the full zone and rule definitions of each preset.

​
tsconfig rootDir detection

When a preset is active, fallow reads compilerOptions.rootDir from tsconfig.json to determine the source root for zone patterns. Preset zones become {rootDir}/{zone}/**. The detection logic:
  1. Reads tsconfig.json from the project root (supports JSONC with comments and trailing commas)
  2. Extracts compilerOptions.rootDir
  3. Strips a leading ./ prefix and any trailing /
  4. Rejects ., .., and absolute paths for security
  5. Falls back to src if the field is missing, the file doesn’t exist, or the value is rejected
tsconfig.json
{
  "compilerOptions": {
    "rootDir": "./lib"
  }
}
With the hexagonal preset, this produces zones: 
lib/adapters/**
lib/ports/**
lib/domain/**
rootDir detection only applies to presets. Custom zones use patterns exactly as written.

​
Custom zones

Define zones manually when presets don’t match your architecture. Each zone has:
FieldTypeDescription
namestringZone identifier used in rules
patternsstring[]Glob patterns relative to the project root, or relative to root when set
autoDiscoverstring[]Directories whose immediate child directories become separate zones named parent/child
rootstring?Optional subtree scope; patterns and autoDiscover paths are resolved relative to this root
{
  "boundaries": {
    "zones": [
      { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
      { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
      { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
    ]
  }
}
Zone classification rules:
  • A file belongs to the first zone whose pattern matches (first-match wins)
  • Files that don’t match any zone are unrestricted — they can import from and be imported by any zone
  • Zone order matters: place more specific patterns before broader ones
Fallow warns when a zone matches zero files. This usually means the glob pattern doesn’t match your directory structure. Run fallow list --boundaries to check file counts per zone.

​
Auto-discovered zones

Use autoDiscover for feature-module boundaries where every immediate child directory should become its own zone. Rules can still reference the logical parent; fallow expands them to the discovered child zones. 
{
  "boundaries": {
    "zones": [
      { "name": "app", "patterns": ["src/app/**"] },
      { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
      { "name": "shared", "patterns": ["src/shared/**"] }
    ],
    "rules": [
      { "from": "app", "allow": ["features", "shared"] },
      { "from": "features", "allow": ["shared"] }
    ]
  }
}
If src/features/auth and src/features/billing exist, fallow list --boundaries shows features/auth and features/billing, and sibling feature imports are checked as cross-zone imports. Explicit child rules, such as from: "features/auth", override generated parent rules regardless of rule order. When the zone also has patterns, discovered child zones are matched first and top-level files inside the auto-discover directory fall back to the parent zone. The parent fallback rule automatically allows its discovered children, so a src/features/index.ts barrel can re-export feature modules without surfacing features → features/<child> violations, while non-barrel top-level files such as src/features/types.ts still obey the parent features rule. Generated child rules keep the original allow list exactly, so sibling-feature isolation is preserved. Omit patterns from the zone when you want only discovered child directories classified and top-level files left unrestricted.

​
Custom rules

Rules define which zones may import from which. Each rule has:
FieldTypeDescription
fromstringThe importing zone
allowstring[]Zones that from may import from
allowTypeOnlystring[]Zones that from may type-only-import from even when not in allow (optional)
{
  "boundaries": {
    "zones": [
      { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
      { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
      { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
    ],
    "rules": [
      { "from": "ui", "allow": ["shared"] },
      { "from": "data", "allow": ["shared"] },
      { "from": "shared", "allow": [] }
    ]
  }
}
Rule semantics:
  • Self-imports are always allowed — files within the same zone can freely import each other
  • No rule entry means the zone is unrestricted — it can import from any zone
  • Empty allow list means the zone is isolated — no cross-zone imports permitted
  • Only zones with an explicit rule entry are constrained
Start with rules for your lowest-level zones (the ones that should import from nothing) and work upward.

​
Type-only imports across boundaries

TypeScript projects sometimes need type-level contracts between modules that must not have runtime dependencies on each other. A plugin system, for example, may declare a contribution interface in one feature that consumers in other features depend on at the type level only: 
// features/metrics-panel/extension-api.ts
export interface MetricsPanelContribution { items?: MetricItemProvider[]; }

// features/extra-metrics/index.ts
import type { MetricsPanelContribution } from '#/features/metrics-panel/extension-api';
The import is fully erased at compile time, so it carries no runtime coupling. To admit it without opening the full allow list to the target zone, add allowTypeOnly: 
{
  "boundaries": {
    "rules": [
      {
        "from": "features/extra-metrics",
        "allow": [],
        "allowTypeOnly": ["features/metrics-panel"]
      }
    ]
  }
}
What allowTypeOnly admits:
  • Whole-declaration type imports: import type { Foo } from '...'
  • Namespace type imports: import type * as ns from '...'
  • Inline-type imports where every named specifier carries the type qualifier: import { type Foo } from '...'
  • Type-only re-exports: export type { Foo } from '...'
What it does NOT admit:
  • Mixed-specifier imports where at least one specifier is value-typed (import { type Foo, Bar }) — the runtime dependency on Bar still fires a violation
  • Plain value imports (import { Foo } from '...')
  • Side-effect imports (import '...') — these run the target at runtime
Semantics:
  • allowTypeOnly is independent of allow. A type-only edge is admitted if its target zone is in EITHER list.
  • The default value is an empty list, so omitting the field preserves pre-feature behavior exactly.
  • No preset (Layered, Hexagonal, FeatureSliced, Bulletproof) defaults the field on; type-only crossings are opt-in per rule.

​
Merging presets with custom config

When both preset and zones/rules are specified, fallow merges them:
  • Zones with the same name as a preset zone replace the preset zone entirely
  • Rules with the same from as a preset rule replace the preset rule
  • New zones and rules are added on top of the preset

​
Example: override a preset zone

Use the hexagonal preset but put your domain code in src/core instead of src/domain: 
{
  "boundaries": {
    "preset": "hexagonal",
    "zones": [
      { "name": "domain", "patterns": ["src/core/**"] }
    ]
  }
}
This keeps adapters and ports from the hexagonal preset but replaces the domain zone pattern with src/core/**. All three rules remain unchanged.

​
Example: add a zone to a preset

Add a test zone to the bulletproof preset so test utilities are isolated: 
{
  "boundaries": {
    "preset": "bulletproof",
    "zones": [
      { "name": "test", "patterns": ["src/__tests__/**", "src/**/*.test.ts"] }
    ],
    "rules": [
      { "from": "test", "allow": ["features", "shared", "server"] }
    ]
  }
}
The four bulletproof zones and their rules are preserved. The test zone and its rule are added on top.

​
Inspecting boundaries

Use fallow list --boundaries to see the expanded configuration after preset expansion and merging. This is the fastest way to verify your config is correct.
$ fallow list --boundaries
Boundaries: 4 zones, 4 rules

Zones:
  app                  3 files  src/app/**
  features             12 files src/features/**
  shared               8 files  src/components/**, src/hooks/**, src/lib/**, ...
  server               4 files  src/server/**

Rules:
  app                  → features, shared, server
  features             → shared, server
  server               → shared
  shared               (isolated — no imports allowed)
For scripting or MCP tools, use JSON output: 
fallow list --boundaries --format json --quiet
Run fallow list --boundaries first when debugging boundary violations. It shows actual zone patterns, file counts, and resolved rules. Misconfigured globs become obvious before running analysis.

​
Common patterns

Preset zone patterns are flat (src/<zone>/**), which doesn’t work when packages have separate source directories. Define zones explicitly for each package:
{
  "boundaries": {
    "zones": [
      { "name": "web-ui", "patterns": ["apps/web/src/components/**", "apps/web/src/pages/**"] },
      { "name": "web-data", "patterns": ["apps/web/src/api/**", "apps/web/src/hooks/**"] },
      { "name": "shared-ui", "patterns": ["packages/ui/src/**"] },
      { "name": "shared-utils", "patterns": ["packages/utils/src/**"] }
    ],
    "rules": [
      { "from": "web-ui", "allow": ["web-data", "shared-ui", "shared-utils"] },
      { "from": "web-data", "allow": ["shared-utils"] },
      { "from": "shared-ui", "allow": ["shared-utils"] },
      { "from": "shared-utils", "allow": [] }
    ]
  }
}
In tRPC apps, the server router typically imports from feature modules to compose sub-routers. With the bulletproof preset, this causes server -> features violations.The cleanest approach is to suppress the router composition file:
src/server/_app.ts
// fallow-ignore-file boundary-violation
import { authRouter } from '../features/auth/router'
import { billingRouter } from '../features/billing/router'

export const appRouter = router({
  auth: authRouter,
  billing: billingRouter,
})
Alternatively, add features to the server rule:
{
  "boundaries": {
    "preset": "bulletproof",
    "rules": [
      { "from": "server", "allow": ["shared", "features"] }
    ]
  }
}
Widening the server rule allows all server files to import from features, not just the router. Prefer inline suppression for surgical exceptions.
Test files often need to import from any zone. Add a test zone that sits above the preset layers:
{
  "boundaries": {
    "preset": "bulletproof",
    "zones": [
      { "name": "test", "patterns": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/__tests__/**"] }
    ],
    "rules": [
      { "from": "test", "allow": ["app", "features", "shared", "server"] }
    ]
  }
}
Since zones use first-match classification, place more specific patterns (like test file globs) before broader zone patterns. When using a preset with custom zones, custom zones are appended after preset zones. If your test files live inside zone directories (e.g., src/features/auth/auth.test.ts), the preset’s features zone pattern will match first. Move the test patterns into an explicit zone list that comes before the preset zones, or use ignorePatterns to exclude test files from boundary analysis entirely.

​
See also

Architecture boundaries

Presets, output formats, and inline suppression for boundary violations.

Rules & Severity

Set boundary-violation to error, warn, or off.

Inline Suppression

Suppress individual findings in source code.