Skip to content
Chisel

Check a SvelteKit frontend

You have a SvelteKit frontend and want chisel-js to find architecture violations in it. This guide installs the TypeScript CLI, runs a check, and explains how to read the output.

Install

Section titled “Install”
Terminal window
npm install -g chisel-js      # or: bun add -g chisel-js
chisel-js --version

Requires Node 20+. Runtime deps (chalk, commander, estree-walker, fast-glob, svelte, typescript) install automatically — TypeScript is used to parse and resolve your imports, so it ships with the CLI.

Initialise

Section titled “Initialise”

Run init once. It works out which topology your project has and writes chisel.config.json:

Terminal window
chisel-js init ./your-frontend
Mode What it means
sveltekit-standalone SvelteKit owns its data layer — Drizzle under $lib/server, no separate backend
sveltekit-bff SvelteKit fronts a separate API through a generated openapi-fetch client

The mode decides which rules apply: a standalone app has repositories and remote functions, a BFF has a generated API client. Detection runs only here — from then on check reads the file, so the rule set can’t change because someone edited a dependency. Override with --mode sveltekit-bff if the guess is wrong.

check still works without a config; it detects a mode, says so, and suggests running init.

The config holds facts about the project that the tree cannot reveal. It never switches a rule off.

{
  "mode": "sveltekit-standalone",
  "designSystem": {
    "allowIn": ["src/lib/components/ui/", "src/lib/components/vendor-editor/"],
    "icons": "$lib/components/icons",
    "tokens": "src/routes/layout.css",
    "headingUtilities": ["page-title", "section-title"],
    "displayUtilities": ["page-title"]
  },
  "entryPoints": ["src/worker.ts"],
  "agent": {
    "tools": "src/lib/server/factories/agent/tools/",
    "toolAdapters": ["src/lib/server/infrastructure/agents/sdk-tool.ts"]
  }
}
Key Fact
designSystem.allowIn Vendored and generated component folders: exempt from the raw-HTML ban; their stylesheets keep their own colour format
designSystem.icons The module every icon comes from; icon libraries are banned elsewhere
designSystem.tokens The stylesheet defining the colour tokens; contrast is checked there
designSystem.headingUtilities / displayUtilities Type-scale utilities a heading may use, and those that render display-size text
entryPoints Process entry points beyond hooks, routes and remote functions, such as a worker
agent.tools The folder whose modules turn controller operations into agent tools
agent.toolAdapters The only files that may construct tools from an agent SDK

Run a check

Section titled “Run a check”

Point chisel-js check at your project root. Default path is ..

Terminal window
chisel-js check ./your-frontend

Non-zero exit on any ERROR-level violation. That’s what makes it safe to gate commits and CI on.

Read the output

Section titled “Read the output”

Coloured, grouped by category, one block per violation. Each violation names the file, line, rule ID, and a short message.

Terminal window
chisel-js check ./your-frontend

For scripts, agents, or CI, ask for JSON; see Understand a violation for how to read the deduplicated --json output.

What’s next

Section titled “What’s next”