Skip to content

Installation

Add a first policy to a TypeScript repository and watch it catch a bad import.

  1. Install the oxlint plugin and the CLI:

    Terminal window
    pnpm add -D @goodbones/oxlint # editor and CI feedback through oxlint
    pnpm add -D @goodbones/cli # the `architecture` command
  2. Enable the plugin’s rules in .oxlintrc.json:

    {
    "jsPlugins": [{ "name": "architecture", "specifier": "@goodbones/oxlint" }],
    "rules": {
    "architecture/imports": "error",
    "architecture/exports": "error",
    "architecture/members": "error",
    "architecture/structure": "error",
    "architecture/surface": "error"
    }
    }

    The plugin also has an architecture/campaigns rule; see Campaigns installation.

  3. Write architecture.yaml at the repository root:

    # yaml-language-server: $schema=https://dataquail.github.io/goodbones/schema/architecture.schema.json
    resolve:
    scopes:
    - files: ""
    language: typescript
    options: { tsconfig: tsconfig.json }
    unresolved: error
    aliases:
    "@": src
    tree:
    "@/domain/":
    imports:
    message: "domain/ may not reach the framework."
    reset: true
    external: [effect]
    allow: ["@/domain/**"]
    children:
    "*.ts": {}

    This says:

    • src/domain/ admits only .ts files.
    • Files there may import only from src/domain/ and effect. Anything else fails with the message.
    • Every import in the repository must resolve to a file.

    Or run pnpm exec architecture init for a starter, or infer one from your code.

  4. Plant a violation and watch it fail:

    Terminal window
    echo 'import "express";' > src/domain/probe.ts
    pnpm oxlint src
    rm src/domain/probe.ts
  5. Run the CLI to check the whole repository, including the graph rules the plugin cannot see:

    Terminal window
    pnpm exec architecture check

The plugin reads the manifest when oxlint starts. A malformed manifest stops the lint with every error at once, each naming its file, line and column. A rule that can no longer match anything also stops it; see probes.

The first-line comment points your YAML extension (such as VS Code’s) at the manifest’s schema, so it completes keys and flags misspellings as you type.