@linnify/eslint-config
v1.3.0
Published
Linnify's shared ESLint flat configs: type-checked TypeScript, the naming, file-shape and readability conventions, and the app, agents, Next.js, React and Tailwind rules every Linnify project lints with.
Keywords
Readme
@linnify/eslint-config
Linnify's shared ESLint flat configs. Every Linnify project lints with them, so a rule changed here reaches every project as a dependency update instead of a copy each team keeps in sync by hand. Every rule is error or off, with no warn tier, and lint scripts run with --max-warnings 0.
Install
In a project started from the Linnify starter, add it to the pnpm catalog in pnpm-workspace.yaml, then reference it as "@linnify/eslint-config": "catalog:" in the devDependencies of every package that lints:
catalog:
'@linnify/eslint-config': 1.2.0
# Linnify's own packages are published only from linnify/asd's CI, through npm
# trusted publishing, so they skip the one-day wait for new releases.
minimumReleaseAgeExclude:
- '@linnify/*'Anywhere else: pnpm add -D @linnify/eslint-config eslint typescript.
Peer dependencies.
eslint(10) is a peer dependency, and the type-checked rules needtypescriptwith atsconfig.jsonbeside each linted package. The plugins come with this package.Expected warning.
eslint-plugin-react7.37.5 declares support only up to ESLint 9, sopnpm peers checkreports it. The configs work around the one call it breaks (react.versionis pinned instead of detected), and the warning goes away once the plugin supports ESLint 10.Recording existing violations. Add the two scripts the starter has to the root
package.json, for adopting the rules on existing code (below):"lint:suppress": "turbo lint --force -- --suppress-all", "lint:prune": "turbo lint --force -- --prune-suppressions"
Pick a config
@linnify/eslint-config/base: packages (packages/*). Type-checked TypeScript rules (recommendedTypeChecked:no-floating-promises,no-misused-promises, theno-unsafe-*family and the rest) plus a relaxed override for*.test.ts(x)files, and the naming conventions:- names in the right casing
- function names that start with a verb and never end in
Of - a
functiondeclaration for a React component, an arrowconstfor every other function - a name on every default-exported function
Plus the readability limits: braces on every
if, no nested ternary, noawaitinside another expression, noflatMapused as a filter, blocks nested at most 2 deep, functions of at most 50 lines (150 in a.tsxfile) and files of at most 400.@linnify/eslint-config/app: apps (apps/*) without a UI, e.g. the Fastify API. Extendsbasewith the app conventions:- no
console - no
process.envoutsidesrc/env - no relative parent imports
- no
@repo/db/generated*imports - every
eslint-disablecomment scoped and described - the file shapes: a
*.plugin.tsor*.routes.tsfile exports only its plugin; a*.service.tsor*.repository.tsfile only its singleton; a utils, hooks, schema, types or constants file only named exports - no module-level constant, schema or function in a
.tsfile that declares a class: what only the class uses is a private member of it
- no
@linnify/eslint-config/agents: an app that hosts AI agents. Spread it afterapp. It keeps each agent insrc/agents/{agent}/, with its agent, instructions, tool, skill, processor and eval files named and default-exported the same way. It keeps the framework's agent, tool and skill constructors inside those files — and a tool several agents share in its feature'stools/, as{feature}-{tool}.tool.ts— names the schema of an agent's structured outputschema, and lets the rest of the app import only an agent's file, types, schemas and constants. One agent imports the same from another, which is how a supervisor lists its subagents. It reports nothing in an app withoutsrc/agents/.@linnify/eslint-config/next: the Next.js web app. Extendsappwith the React, react-hooks and Next.js rules, andtailwind.@linnify/eslint-config/expo: the Expo (React Native) app. It extendsappwith the React and react-hooks rules, and addstailwindwithout the three rules that assume Tailwind v4 and CSS, because NativeWind runs Tailwind v3 on React Native styles:no-inline-styles, sincestyleis React Native's own stylingno-unknown-classes, since v3 class names and the project's tokens read as unknownno-restyle, since a primitive like<Text>takes its colour per use
It also allows
require()for assets andprocess.envin the env module (where Expo inlinesEXPO_PUBLIC_variables), gives the root*.config.jsfiles Node globals, and ignoresios/,android/and.expo/.@linnify/eslint-config/react: React libraries that are not Next.js apps.@linnify/eslint-config/tailwind: the design-system rules of@shadcn/lintfor any app styled with Tailwind: theme tokens instead of raw palette colours, scale values instead of arbitrary ones, classes instead of inline styles, component variants instead of restyling. It reads the theme and the components fromcomponents.jsononce shadcn/ui is set up; before that, raw palette colours are still reported. Spread it after the app's config;nextandexpoalready include it.
In a package's eslint.config.js:
import { config } from '@linnify/eslint-config/app';
/** @type {import("eslint").Linter.Config[]} */
export default config;Naming and readability conventions
The rules live in conventions.js, which base and app both read.
A function name starts with a verb.
FUNCTION_VERBSis the list of verbs a name may start with. When a good name fails because its verb is missing from the list, add the verb here (a patch release) instead of disabling the rule. Until that release reaches the project, record the violation withpnpm lint:suppress.The verb rule accepts what the code doesn't choose itself:
- a
soft,hardorbulkmodifier before the verb (softDeleteComment) - TanStack Query options named
{feature}QueryOptions, as the web knowledge names them - the methods of a class that
implementsan interface, since the interface names them (childon a logger an SDK defines)
- a
The file shapes share
no-restricted-syntaxwith the verb rule. A config block replaces that rule's whole option list, so a block that adds its own selectors spreads the shared ones too:sharedSelectorsin a package,appSelectorsin an app, the wayapp.jsandagents.jsdo. A project imports them from@linnify/eslint-config/conventions:import { config } from '@linnify/eslint-config/app'; import { appSelectors } from '@linnify/eslint-config/conventions'; export default [ ...config, { files: ['src/jobs/**/*.ts'], rules: { 'no-restricted-syntax': ['error', ...appSelectors, { selector: '…', message: '…' }] } } ];An error class is allowed beside helpers. A utils file may declare
…Errorclasses; only another class makes a file a class file, whose constants and helpers belong inside the class.Every message says how to fix the code. A person or an agent fixes a failure from its message alone, so each message says what is wrong, the change to make, and an example of it. ESLint's own
curly,max-depth,max-linesandmax-lines-per-functionrun asconventions/*rules for that reason: the same rules, with messages that say what to do. Write any new rule the same way.Existing violations are recorded, never disabled. A project that adopts these rules on code written before them runs
pnpm lint:suppressonce. ESLint writes aneslint-suppressions.jsonper package; the recorded violations stop failing, and every new one still fails.pnpm lint:prunedrops the entries a fix made obsolete.Generated components are exempt. shadcn/ui writes and rewrites
components/ui/andhooks/use-mobile.ts, so the naming and readability rules are off there.Scripts may log.
no-consoleis off underscripts/, in*.script.tsfiles a person runs by hand, and in the env module, which reports invalid configuration before the logger exists.An
awaitthat runs on one path only stays where it is: a branch of a ternary, or the right of??,||or&&(overrides.userId ?? (await createUser()).id). Moving it out would run it every time.A disable comment that disables nothing is an error, like every other finding.
Versions
A project started from the Linnify starter takes patch releases automatically: its Dependabot raises patch updates only, a week after they are published, and merges them once the project's checks pass. It takes minor and major releases by hand, because a new failing rule needs someone to fix or record the violations it finds.
| Release | What changes |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| patch | Nothing that fails today's code more: a clearer message, a fixed false positive, a verb added to FUNCTION_VERBS, a plugin patch. |
| minor | Something a project may need to act on: a new rule, a stricter limit, a new config entry point, a plugin minor. |
| major | Something that breaks the setup: a removed or renamed entry point, a new peer dependency or a major of one, a dropped Node version. |
To take a minor or a major in a project: pnpm up @linnify/eslint-config@latest, pnpm lint, then fix the new violations or record them with pnpm lint:suppress.
Change it
This package lives in linnify/asd under configs/eslint/. In the same PR as the change:
- Add or update a test in
test/. Each test lints a snippet in a throwaway TypeScript project with the real config and asserts which rule reports it, so the type-checked rules run too.pnpm --filter @linnify/eslint-config testruns them. - Bump
versioninpackage.jsonby the table above.
The push to main publishes the new version to npm (.github/workflows/publish-eslint-config.yml) and tags it eslint-config-v{version}.
