Getting started

Install

Install shapelint as a development dependency:

pnpm

pnpm add -D shapelint

npm

npm install -D shapelint

yarn

yarn add -D shapelint

bun

bun add -d shapelint

This gives you the shapelint CLI (also aliased as shape) and the typed defineConfig / defineRule helpers.

Create a config

Add shapelint.config.ts to your project root:

import { defineConfig } from 'shapelint';

export default defineConfig({
  root: 'src',
  rules: [
    {
      name: 'ui-component',
      files: 'components/ui/**/*.tsx',
      pattern: `
        interface IProps {}

        const $Name: React.FC<IProps> = () => {}

        export default $Name
      `,
      filename: '$Name.tsx',
    },
  ],
});

The config is loaded with jiti, so a TypeScript config works with no build step. .js and .mjs configs are also supported.

Framework-Agnostic

Shapelint works across any stack—React, Vue, Svelte, Angular, NestJS, Express, or pure TypeScript. Simply declare rules that match your project's conventions. See the Example config for multi-paradigm rule patterns.

No-install option

If you can't install the package (for example, running it against an unrelated repo), export a plain object instead of using defineConfig, and invoke the CLI by path:

// shapelint.config.ts, no import needed
export default {
  root: 'src',
  rules: [
    /* ... */
  ],
};

node /path/to/shapelint/dist/cli.js check

Run the check

npx shapelint check

• Clean tree → prints ✔ no architecture violations, exits 0.
• Violations → prints one block per finding, exits 1.
• Config problem (missing / invalid / no rules) → exits 2.

Config is discovered by walking up from the current directory, so you can run shapelint check from any subfolder.

Prefer not to write the config by hand? See Generate a config with AI, a copy-paste prompt that has an agent scan your repo and write the whole config.

Wire it into your workflow

• Pre-commit / CI: run shapelint check; a non-zero exit fails the gate.
• With an agent: tell the agent once to run npx shapelint check after editing and fix what it reports. The diagnostic is written to be actioned in a single pass, see diagnostics.

For AI agents

The complete machine-readable spec lives at /llms.txt, hand it to any agent to teach it Shapelint's full config schema and CLI.