eslint-plugin-stackrules

eslint-plugin-stackrules

ESLint plugin that enforces clean architecture in AI-generated codebases.

AI writes code that works but creates spaghetti — Supabase calls in components, Stripe inline, no service layer, no logging, duplicate functions everywhere. StackRules catches every bad pattern and tells the AI exactly how to fix it.

Works on top of ESLint. You keep your existing rules. StackRules adds the architecture layer.

Install

npm install --save-dev eslint-plugin-stackrules

Or use the CLI for zero-config setup:

npx create-stackrules inject

Setup

Flat config (ESLint 9+):

// eslint.config.mjs
import stackrules from "eslint-plugin-stackrules";

export default [
  {
    plugins: { stackrules },
    rules: {
      "stackrules/no-service-in-components": "error",
      "stackrules/page-complexity": "warn",
      "stackrules/code-quality": "warn",
      // ... see all rules below
    },
  },
];

Legacy config:

{
  "extends": ["plugin:stackrules/recommended"],
  "plugins": ["stackrules"]
}

Rules

Architecture enforcement

Rule	Default	What it catches
no-service-in-components	error	Database, payment, email, HTTP, AI, cloud SDKs imported outside services/. Covers 50+ packages automatically. Different messages for pages vs API routes vs backend routes.
services-must-log	error	Service files that don't import and use a logger. Every service function must log params, result, duration, errors.
no-side-effects-in-utils	error	API calls, service imports, or side effects in utils/ files. Utils must be pure functions.
no-raw-sql	error	Raw SQL strings. Use Supabase client methods, Prisma, Drizzle, or any ORM instead.
no-eslint-disable	error	All eslint-disable comments. AI must fix violations, not suppress them.
no-business-logic-in-components	warn	Components importing directly from services/. Components should use hooks.

AI-quality refactoring guidance

Rule	Default	What it does
page-complexity	warn	Analyzes pages, API routes, hooks, backend routes, and components. Counts state variables, handler functions, JSX lines. When a file is too complex, outputs a full refactoring plan naming the exact functions to extract, exact files to create, and what the file should look like after.
code-quality	warn	Enforces developer-readable code. Exported functions must have comments. Functions over 40 lines get flagged. Magic numbers must be named constants. Single-letter variables caught. Empty catch blocks flagged.

Reusability enforcement

Rule	Default	What it catches
no-inline-component	warn	Large blocks of raw HTML (15+ div/span/p elements) that should be extracted to reusable components. Composing existing components (Card, Button) is fine.
no-duplicate-logic	warn	Repeated useState + useEffect patterns that should be custom hooks.
no-duplicate-utils	warn	Common utility function names that likely already exist in the codebase.
prefer-shadcn	warn	Native HTML elements (<button>, <input>) styled with Tailwind when a shadcn component exists.

How it works

StackRules works on top of ESLint. ESLint parses the code and walks the AST. StackRules detects architectural patterns and writes errors that are prompts.

Every error message is written so that AI (Cursor, Claude Code, Copilot) can read it and fix the violation automatically. A vibe coder can copy-paste the error into any chat and get a fix.

Example output for a 450-line page:

This page has 15 state variables, 3 handler functions, and 275 lines of JSX.

Refactor plan:
1. Extract loadProfile(), handleSave(), handleFileUpload() -> services/profile.ts
   (every function logs params, result, duration, errors)
2. Extract state (loading, saving, uploading, ...) + data loading -> hooks/useProfile.ts
   — this hook calls the service, manages loading/error/data state
3. Break the 275-line JSX into smaller components in components/

After refactor, this page should be ~30 lines: import useProfile,
destructure state + handlers, render components with props. Zero business logic.

Org config

Create .stackrules.json in your project root to customize behavior:

{
  "customServices": [
    { "package": "my-internal-sdk", "category": "backend" }
  ],
  "codeQuality": {
    "requireCommentsOnExports": true,
    "maxFunctionLines": 40,
    "noMagicNumbers": true,
    "noSingleLetterVars": true,
    "requireErrorHandling": true
  }
}

Service registry

no-service-in-components has a built-in registry of 50+ packages across 9 categories:

• Database — Supabase, Prisma, Drizzle, Mongoose, TypeORM, Sequelize, Firebase, pg, mysql2
• Payment — Stripe, PayPal, Razorpay, LemonSqueezy
• Email — Resend, Nodemailer, SendGrid, Postmark
• HTTP — axios, node-fetch, got, ky, undici
• AI — OpenAI, Anthropic, Replicate
• Cloud — AWS SDK, Google Cloud, Azure
• Auth — NextAuth, Clerk, Lucia
• Messaging — Twilio, Pusher
• Storage — UploadThing, Cloudinary

Add your own via customServices in .stackrules.json or rule options.

License

MIT