Configuration

Archora reads an optional archora.config.{ts,js,json,mjs,cjs} from the project root. Without a config file, it works on sane defaults — the config is for tweaks.

Schema

// archora.config.ts
import { defineConfig } from '@archora/core/config';

export default defineConfig({
  // file discovery
  include: ['src/**/*'],
  exclude: ['**/*.spec.ts', '**/__tests__/**'],

  // declared layers (FSD-style or your own)
  // direction is "may import": app → pages → widgets → features → entities → shared
  layers: [
    { name: 'app',      patterns: ['src/app/**'] },
    { name: 'pages',    patterns: ['src/pages/**'] },
    { name: 'widgets',  patterns: ['src/widgets/**'] },
    { name: 'features', patterns: ['src/features/**'] },
    { name: 'entities', patterns: ['src/entities/**'] },
    { name: 'shared',   patterns: ['src/shared/**'] },
  ],

  // editor jump-to-file (set FRONTSCOPE_EDITOR env var as alternative)
  editor: 'vscode', // 'vscode' | 'webstorm' | 'cursor' | 'idea' | string
});

Layers

A layer is a named bucket of modules. The order in layers defines what's allowed to import what — earlier layers may import later ones, never the other way around.

A reverse import is reported as a layer violation in the Insights panel. You can also gate CI on this — see check.

Per-module overrides via .archora.json

archora.config.{ts,js,json} defines the layer order and the default glob → layer mapping. For one-off overrides — "this single helper actually belongs in shared, not in features where its path lives" — there's a sibling .archora.json:

{
  "layerOverrides": {
    "src/features/auth/lib/jwt.ts": "shared",
    "src/legacy/**": "infra"
  }
}

.archora.json is meant to be committed alongside the codebase: overrides are project-level architectural decisions, not personal preferences. The desktop app has a GUI editor for this file under the Layers icon in the project TopBar (/project/:id/layer-rules) — live-preview of violations on every keystroke, atomic save that preserves any other fields in the JSON. See Working with the graph.

Excluded code

Tests and stories are excluded by default (*.test.*, *.spec.*, *.stories.*). Generated .d.ts files are excluded. Build configs (vite.config, webpack.config, ...) are detected and marked as infra — they stay in the graph but are filtered out of metrics by default.

Without a config

Without a config file, Archora:

• Includes everything under the detected entry points.
• Has no layer rules (so no layer violations are reported).
• Uses vscode for "Open in editor".

This is enough for a first scan. Add a config when you want layer enforcement or to tighten the discovery globs.