@kirill.konshin/lint 0.7.2 → 0.7.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +7 -3
- package/rules/auth.md +3 -3
- package/rules/db.md +5 -9
- package/rules/github.md +1 -1
- package/rules/gitlab.md +1 -1
- package/rules/i18n.md +3 -0
- package/rules/monorepo-turbo-nx.md +38 -4
- package/rules/mui.md +6 -18
- package/rules/nextjs.md +12 -12
- package/rules/npm-yarn.md +28 -118
- package/rules/nx.md +1 -1
- package/rules/playwright.md +1 -1
- package/rules/react.md +8 -9
- package/rules/tailwind.md +7 -46
- package/rules/testing.md +2 -2
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +5 -1
- package/rules/ui-kit.md +6 -0
- package/skills/lint-db/SKILL.md +21 -0
- package/skills/lint-electron/SKILL.md +7 -6
- package/skills/lint-github/SKILL.md +5 -6
- package/skills/lint-gitlab/SKILL.md +4 -4
- package/skills/lint-migrate/SKILL.md +1 -1
- package/skills/lint-mui/SKILL.md +31 -0
- package/skills/lint-nextjs/SKILL.md +33 -8
- package/skills/lint-npm-yarn/SKILL.md +140 -0
- package/skills/lint-repo/SKILL.md +6 -6
- package/skills/lint-tailwind/SKILL.md +53 -0
- package/skills/lint-webstorm/SKILL.md +2 -2
- package/skills/lint-worktree/SKILL.md +2 -2
- package/skills/spec-author/SKILL.md +2 -2
- package/skills/spec-steward/references/apply.md +1 -1
- package/skills/spec-steward/references/contract.md +1 -1
- package/skills/spec-steward/references/model.md +2 -2
- package/skills/spec-steward/references/review-format.md +4 -4
- package/skills/spec-steward/references/wiring.md +1 -1
- package/skills/spec-steward/references/worker.md +1 -1
- package/skills/spec-tools/references/rules/common.md +1 -1
- package/skills/spec-tools/references/rules/spec-steward.md +1 -1
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kirill.konshin/lint",
|
|
3
3
|
"description": "Vite+ (Oxlint + Oxfmt), ESLint + Prettier + lint-staged configs and AI agent rules/skills for monorepos",
|
|
4
|
-
"version": "0.7.
|
|
4
|
+
"version": "0.7.4",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
@@ -108,8 +108,9 @@
|
|
|
108
108
|
"storybook": "^10",
|
|
109
109
|
"tailwindcss": "^4",
|
|
110
110
|
"typescript": "^6",
|
|
111
|
-
"vite": "^8",
|
|
112
|
-
"
|
|
111
|
+
"vite": "^8 || ^1.3.0",
|
|
112
|
+
"vite-plus": "^1.3.0",
|
|
113
|
+
"vitest": "^4 || ^5"
|
|
113
114
|
},
|
|
114
115
|
"peerDependenciesMeta": {
|
|
115
116
|
"eslint": {
|
|
@@ -139,6 +140,9 @@
|
|
|
139
140
|
"vite": {
|
|
140
141
|
"optional": true
|
|
141
142
|
},
|
|
143
|
+
"vite-plus": {
|
|
144
|
+
"optional": true
|
|
145
|
+
},
|
|
142
146
|
"vitest": {
|
|
143
147
|
"optional": true
|
|
144
148
|
}
|
package/rules/auth.md
CHANGED
|
@@ -10,8 +10,8 @@ paths:
|
|
|
10
10
|
- Follow the canonical patterns from the [package README](https://github.com/kirill-konshin/utils/blob/main/packages/auth/README.md) (session module, layout guard, login page, actions, route handlers, proxy) and its migration table when refactoring existing hand-rolled auth
|
|
11
11
|
- ONE auth instance per app in `src/auth.ts`: `createPasswordAuth` (password-protected admin) or `createAuth` (token/OAuth)
|
|
12
12
|
- `isValid` defaults to checking the lib-owned `AUTHENTICATED` marker field (set by `login()`, default session shape `PasswordSession`, nothing to configure) — token/OAuth apps pass their own session type + `isValid` (e.g. access token present & not expired)
|
|
13
|
-
- Pass Next's `Route` as the routes generic (`createPasswordAuth<Route>` / `createAuth<Session, Route>`) so `urls` and the return-URL helpers are type-checked (`typedRoutes` is set by `defineNextConfig`, see nextjs.md)
|
|
14
|
-
- Auth module MUST start with `import 'server-only'` and MUST NOT be module-level `'use server'` (that would expose session getters as callable server actions) — export `loginAction`/`logoutAction` from the SAME module as thin async wrappers with function-level `'use server'`, NO separate `actions.ts`; plain re-exports (`export const loginAction = auth.loginFormAction`) are NOT registered as actions; ENFORCED BY AGENT: no ESLint rule checks this, add on creation, flag on review (see nextjs.md)
|
|
13
|
+
- Pass Next's `Route` as the routes generic (`createPasswordAuth<Route>` / `createAuth<Session, Route>`) so `urls` and the return-URL helpers are type-checked (`typedRoutes` is set by `defineNextConfig`, see [nextjs.md](nextjs.md))
|
|
14
|
+
- Auth module MUST start with `import 'server-only'` and MUST NOT be module-level `'use server'` (that would expose session getters as callable server actions) — export `loginAction`/`logoutAction` from the SAME module as thin async wrappers with function-level `'use server'`, NO separate `actions.ts`; plain re-exports (`export const loginAction = auth.loginFormAction`) are NOT registered as actions; ENFORCED BY AGENT: no ESLint rule checks this, add on creation, flag on review (see [nextjs.md](nextjs.md))
|
|
15
15
|
- Client Components MUST NOT import the auth module (`server-only` + function-level actions are not client-importable) — Server Components pass `loginAction`/`logoutAction` down as props
|
|
16
16
|
- Cookie name MUST be unique per app (`<app>_session`), NEVER generic `session`
|
|
17
17
|
- Cookie secret `SESSION_SECRET` (≥32 chars) and login password `ADMIN_PASSWORD` are SEPARATE env vars, never reuse one for the other
|
|
@@ -19,7 +19,7 @@ paths:
|
|
|
19
19
|
- Guard pages/layouts with `redirectNonAuthenticated()` (redirects to login), Server Actions and Route Handlers with `throwNonAuthenticated()` or `authenticatedRouteHandler()` (401), the whole `/api` surface with `proxyGuard()` in `proxy.ts`, login page with `redirectIfAuthenticated()`
|
|
20
20
|
- Declare API visibility as `urls.public` / `urls.protected` globs and keep them exhaustive — `proxyGuard()` throws on overlap and warns (treating as public) on unknown paths; `allow` is only for request-level tweaks
|
|
21
21
|
- Session lifetime via `ttl` (seconds) ONLY, NEVER set `cookieOptions.maxAge` (iron-session derives it)
|
|
22
|
-
- Logout via `auth.logout()` (destroy + redirect) —
|
|
22
|
+
- Logout via `auth.logout()` (destroy + redirect) — export `logoutAction` as a function-level `'use server'` wrapper, like `loginAction`; a `FormData` argument from `<form action>` is ignored
|
|
23
23
|
- Preserve the return URL through the `state` search param / hidden form field on login redirects; ALWAYS extract it with `auth.getState()` (accepts `await searchParams`, `URLSearchParams`, `FormData`, `NextRequest`, raw string; allows internal paths only, never the login page, falls back to `urls.afterLogin`), NEVER hand-parse `state`
|
|
24
24
|
- NEVER store the return URL in the session — concurrent tabs share the cookie and would clash; thread it ONLY via search params, form fields and the `x-pathname` header
|
|
25
25
|
- `proxy.ts` is two lines: `export const config = { matcher: [...] };` (a LITERAL — Next.js parses it statically) + `export const proxy = auth.proxyGuard({ matcher: config.matcher });` — the guard verifies the matcher covers all `urls.public`/`urls.protected` globs (it may be broader) and THROWS on uncovered ones
|
package/rules/db.md
CHANGED
|
@@ -3,6 +3,8 @@ type: always_apply
|
|
|
3
3
|
description: Database persistence and migration rules
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
Migration and import procedures, Neon: the `lint-db` skill.
|
|
7
|
+
|
|
6
8
|
# IndexedDB
|
|
7
9
|
|
|
8
10
|
- Use Dexie for browser-owned IndexedDB data.
|
|
@@ -20,15 +22,9 @@ description: Database persistence and migration rules
|
|
|
20
22
|
- Use `DATABASE_URL` at runtime; prefer `DATABASE_URL_UNPOOLED` for migrations and maintenance when available.
|
|
21
23
|
- Close owned pools in `finally`; do not leak clients or hide ownership of long-lived connections.
|
|
22
24
|
- Enforce user and tenant scope on every read and mutation; authentication alone is not authorization.
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
- Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
|
|
26
|
-
- After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
|
|
25
|
+
- Never delete server data only because a mutable export became smaller
|
|
26
|
+
- Data migrations, importers and schema changes: follow the `lint-db` skill
|
|
27
27
|
|
|
28
28
|
# Neon
|
|
29
29
|
|
|
30
|
-
Only
|
|
31
|
-
|
|
32
|
-
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
33
|
-
- Use Neon Postgres with Drizzle and checked-in generated migrations.
|
|
34
|
-
- Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
|
30
|
+
- Only if the user asks for Neon, or the project already uses it: follow the `lint-db` skill
|
package/rules/github.md
CHANGED
|
@@ -8,7 +8,7 @@ paths:
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
- Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node -> restore Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
|
|
11
|
-
- Yarn cache: follow npm-yarn.md
|
|
11
|
+
- Yarn cache: follow [npm-yarn.md](npm-yarn.md#install-on-ci). Use the key `${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}` and the restore key `${{ runner.os }}-yarn-`.
|
|
12
12
|
- With an `install` job, only this job saves the Yarn cache. The other jobs `need` it and restore with `actions/cache/restore`. See the `lint-github` skill.
|
|
13
13
|
- Key build caches per commit when jobs run one after another: key `${{ runner.os }}-<tool>-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-`. A later job gets an exact hit and does not save again.
|
|
14
14
|
- Key build caches per job and commit when jobs run in parallel: key `${{ runner.os }}-<tool>-${{ github.job }}-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-${{ github.job }}-`. Only the first job that saves a key keeps its outputs. A downstream job restores the producing job's key and does not save.
|
package/rules/gitlab.md
CHANGED
|
@@ -10,7 +10,7 @@ paths:
|
|
|
10
10
|
- Always collect coverage from tests
|
|
11
11
|
- Always publish important build stats as artifacts
|
|
12
12
|
- Agentic review MUST verify this effective CI order: checkout and cache restore -> enable Corepack -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
|
|
13
|
-
- Yarn cache: follow npm-yarn.md
|
|
13
|
+
- Yarn cache: follow [npm-yarn.md](npm-yarn.md#install-on-ci). Key it per branch, with the default branch as the fallback key.
|
|
14
14
|
- The fallback to the default-branch cache works only when "Use separate caches for protected branches" is cleared (Settings > CI/CD > General pipelines). Otherwise GitLab adds `-protected` or `-non_protected` to all keys, and other branches never find the default-branch cache. GitLab: clear it only when all users with the Developer role are highly trusted.
|
|
15
15
|
- With an `install` job, only this job has Yarn cache `policy: pull-push`. The other jobs use `policy: pull`. See the `lint-gitlab` skill.
|
|
16
16
|
- Use the fastzip archiver for cache and artifacts. It is the default from GitLab Runner 19.4. On older runners, set `FF_USE_FASTZIP: 'true'`.
|
package/rules/i18n.md
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
type: always_apply
|
|
3
|
-
description: Set of rules for MONOREPO projects which use Turbo or
|
|
3
|
+
description: Set of rules for MONOREPO projects which use Turbo, NX or Vite+
|
|
4
4
|
paths:
|
|
5
5
|
- '**/turbo.json'
|
|
6
6
|
- '**/nx.json'
|
|
7
7
|
- '**/package.json'
|
|
8
8
|
- '**/project.json'
|
|
9
|
+
- '**/vite.config.ts'
|
|
9
10
|
---
|
|
10
11
|
|
|
11
12
|
- Existing projects may use what they use
|
|
@@ -14,7 +15,25 @@ paths:
|
|
|
14
15
|
- Tasks to launch inner tasks (main `build` that launches `build` in each sub-package)
|
|
15
16
|
- Inner `package.json` MUST only define atomic orchestrator-agnostic tasks
|
|
16
17
|
- Repo-wide defaults (parallelism, worker counts, cache and tool settings) live in env files (`.env`) or tool configs (`nx.json`, `turbo.json`, `vite.config.ts`), NEVER in `package.json` scripts — scripts stay as simple as possible; CI-specific behavior is set on the CI command (flags or env) where it is needed
|
|
17
|
-
|
|
18
|
+
|
|
19
|
+
# Orchestrator Choice
|
|
20
|
+
|
|
21
|
+
- IF NX Release publishes the packages, use NX for cache and task management
|
|
22
|
+
- ELSE use Vite+ (`vp run`) — the default
|
|
23
|
+
- IF Turbo is already used, keep it and offer to migrate: to NX if NX Release publishes, else to Vite+
|
|
24
|
+
|
|
25
|
+
# Vite+ Task Runner
|
|
26
|
+
|
|
27
|
+
https://viteplus.dev/guide/cache
|
|
28
|
+
|
|
29
|
+
- Only `vp run` caches; a direct `vp build` / `vp test` does not
|
|
30
|
+
- Define cacheable tasks in `vite.config.ts` `run.tasks` (cached by default); `package.json` scripts are cached only with `--cache` or `run.cache.scripts: true`
|
|
31
|
+
- `clean`, `wait`, `start` / `dev` tasks: `cache: false`
|
|
32
|
+
- Tasks run in a clean environment: list env vars that change outputs in `cache.env`, pass-through ones in `cache.untrackedEnv`
|
|
33
|
+
- Verify each task: the second `vp run <task>` MUST print `cache hit`; else fix `cache.input` / `cache.output`
|
|
34
|
+
- Cache lives in `node_modules/.vite/task-cache`; clear with `vp cache clean`; CI reuse: see [npm-yarn.md](npm-yarn.md#install-on-ci)
|
|
35
|
+
- No `affected` command: PR runs are fast only when CI restores the task cache
|
|
36
|
+
- Concurrency defaults to 4 tasks: `--concurrency-limit` or `VP_RUN_CONCURRENCY_LIMIT`; `--parallel` is unlimited
|
|
18
37
|
|
|
19
38
|
# Test Ownership
|
|
20
39
|
|
|
@@ -22,7 +41,7 @@ paths:
|
|
|
22
41
|
- The test tool at the root (Vitest `test.projects`, Jest `projects`) is the local / IDE full-speed run: one worker pool over every package, all cores, no cache
|
|
23
42
|
- Inside an orchestrator task a test runner takes half of the cores, as the orchestrator runs several tasks at once (Nx: detect with `NX_TASK_TARGET_PROJECT`)
|
|
24
43
|
- Type checking (`vp check`, `tsc`) resolves workspace packages through their built declarations: CI lint jobs run after the build job (`needs: build`) and build the packages first through the orchestrator (cache hits), and so does a fresh clone before `lint`
|
|
25
|
-
- Suites that need running apps (e2e, integration): the orchestrator starts them — the test target `dependsOn` the continuous `start` / `dev` / `serve` plus a `wait` probe, `cache: false` — or Docker Compose does; the test tool never starts them (Playwright `webServer`), see playwright.md and testing.md
|
|
44
|
+
- Suites that need running apps (e2e, integration): the orchestrator starts them — the test target `dependsOn` the continuous `start` / `dev` / `serve` plus a `wait` probe, `cache: false` — or Docker Compose does; the test tool never starts them (Playwright `webServer`), see [playwright.md](playwright.md) and [testing.md](testing.md)
|
|
26
45
|
|
|
27
46
|
# Task Consistency
|
|
28
47
|
|
|
@@ -65,4 +84,19 @@ The `start` task uses `"dependsOn": ["^wait"]` (upstream):
|
|
|
65
84
|
4. Once the file exists, `B`'s `wait-on` unblocks and exits, and `A`'s `start` can proceed
|
|
66
85
|
5. If file existed before, `A` starts immediately, the only issue could be `A`'s double-build if `B`'s `start` will eventually modify the file, causing `A`'s watcher to rebuild
|
|
67
86
|
|
|
68
|
-
For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in turbo.md.
|
|
87
|
+
For Turbo sibling runtime services (`web` <> `api`, not a package dependency) see the `with` + `wait` pattern in [turbo.md](turbo.md).
|
|
88
|
+
|
|
89
|
+
## Vite+
|
|
90
|
+
|
|
91
|
+
Vite Task has no `persistent` / `continuous` tasks (verified on 1.3.0):
|
|
92
|
+
|
|
93
|
+
- `vp run -r start` waits for upstream `start` to exit, so downstream `start` never starts, `^wait` or not (https://github.com/voidzero-dev/vite-task/issues/258)
|
|
94
|
+
- `--parallel` ignores every `dependsOn`, `^wait` included
|
|
95
|
+
- `dependsOn` a persistent task is not supported (https://github.com/voidzero-dev/vite-task/issues/416)
|
|
96
|
+
|
|
97
|
+
Chain the upstream probe inside the downstream command instead:
|
|
98
|
+
|
|
99
|
+
- Root: `"start": "vp run -r --parallel start"`
|
|
100
|
+
- Downstream package `A`: `"start": "vp run --filter 'A^...' wait && <watcher>"` — write the package name, `.^...` does not resolve
|
|
101
|
+
- Upstream package `B` defines `wait` as above
|
|
102
|
+
- Stopping only the `vp` process orphans its tasks; stop the whole process group (https://github.com/voidzero-dev/vite-plus/issues/3090)
|
package/rules/mui.md
CHANGED
|
@@ -1,24 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
type: always_apply
|
|
3
3
|
description: Set of rules for projects with MUI
|
|
4
|
+
paths:
|
|
5
|
+
- '**/*.tsx'
|
|
6
|
+
- '**/*.ts'
|
|
4
7
|
---
|
|
5
8
|
|
|
6
|
-
|
|
7
|
-
- See barrel handling section
|
|
8
|
-
- Exception: if developing a library use direct imports with minimal bundle footprint (libraries may not be used with barrel handling)
|
|
9
|
-
- To use MUI default classes always use stable minifiable class names:
|
|
10
|
-
- Import: `import { inputClasses } from '@mui/material';` or `import { inputClasses } from '@mui/material/Input';` (see rule about imports)
|
|
11
|
-
- Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
|
|
12
|
-
- Define safe-area insets globally or in the theme; consume through `sx`, never repeated `env(...)`
|
|
9
|
+
Details and admin pages: the `lint-mui` skill.
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see tailwind.md)
|
|
17
|
-
- ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
|
|
18
|
-
- ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) over hand-rolled `NextAppProvider`/`DashboardLayout`/`SignInPage` boilerplate; `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` (see auth.md)
|
|
19
|
-
- Prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled equivalents
|
|
20
|
-
|
|
21
|
-
# Next.js
|
|
22
|
-
|
|
23
|
-
- When MUI is used with Next.js ALWAYS add barrel-heavy packages to `experimental.optimizePackageImports`: `@mui/material`, `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/x-data-grid`, `@toolpad/core`, plus the other usual suspects (`@fortawesome/*`, `@gravity-ui/icons`, `@gravity-ui/uikit`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`)
|
|
24
|
-
- Prefer `defineNextConfig` from `@kirill.konshin/next/config` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see nextjs.md)
|
|
11
|
+
- Import from the barrels (`@mui/material`, `@mui/icons-material`) in apps; use direct imports (`@mui/material/Button`) in libraries
|
|
12
|
+
- Target MUI default classes only through the stable `*Classes` names (e.g. `inputClasses.root`), never through literal class strings
|
package/rules/nextjs.md
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
1
|
---
|
|
2
2
|
type: always_apply
|
|
3
3
|
description: Set of rules for projects which use Next.js
|
|
4
|
+
paths:
|
|
5
|
+
- '**/next.config.*'
|
|
6
|
+
- '**/app/**'
|
|
7
|
+
- '**/proxy.ts'
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
_EVERY_ Next.js page, layout, route handler or component must adhere to policy unless explicitly prohibited in comment before the component definition.
|
|
7
11
|
|
|
8
|
-
Use `lint-nextjs` skill when working with Next.js
|
|
12
|
+
Use the `lint-nextjs` skill when working with a Next.js project.
|
|
9
13
|
|
|
10
14
|
# General Guidelines
|
|
11
15
|
|
|
12
16
|
- Prefer Route Handlers for redirects
|
|
13
17
|
- Never use Pages Router
|
|
14
18
|
- Always use App Router
|
|
15
|
-
- Use `iron-session` for authentication via `@kirill.konshin/auth`, see auth.md
|
|
16
|
-
- Server-only modules
|
|
19
|
+
- Use `iron-session` for authentication via `@kirill.konshin/auth`, see [auth.md](auth.md)
|
|
20
|
+
- Server-only modules MUST start with `import 'server-only'`: see [typescript.md](typescript.md)
|
|
17
21
|
- `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
|
|
18
|
-
- ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler)
|
|
22
|
+
- ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler); what it sets: the `lint-nextjs` skill
|
|
19
23
|
- Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it)
|
|
20
|
-
-
|
|
21
|
-
- Reusable components should be in `src/components`
|
|
22
|
-
- As exception, separate component files are allowed to be in `src/app` next to relevant pages if one-off component is large so page itself becomes bloated, but `src/components` should not be polluted with one-offs, ask user if not sure
|
|
23
|
-
- Example: `actions.ts` for `'use server'` actions while page is `'use client'`
|
|
24
|
+
- Page and component file placement: the `lint-nextjs` skill
|
|
24
25
|
|
|
25
26
|
# Admin Pages & Login
|
|
26
27
|
|
|
27
|
-
- ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see mui
|
|
28
|
-
- ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see mui
|
|
29
|
-
-
|
|
30
|
-
- Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
|
|
28
|
+
- ALWAYS use MUI + [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens, with the App Router integration (`NextAppProvider` from `@toolpad/core/nextjs`), see the `lint-mui` skill
|
|
29
|
+
- ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see the `lint-mui` skill
|
|
30
|
+
- Tailwind is ONLY for user-facing sites, NEVER for admin (see [tailwind.md](tailwind.md))
|
package/rules/npm-yarn.md
CHANGED
|
@@ -1,8 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
type: always_apply
|
|
3
3
|
description: NPM & Yarn patterns
|
|
4
|
+
paths:
|
|
5
|
+
- '**/package.json'
|
|
6
|
+
- '**/.yarnrc.yml'
|
|
7
|
+
- '**/yarn.config.cjs'
|
|
8
|
+
- '**/.npmrc'
|
|
9
|
+
- '**/pnpm-workspace.yaml'
|
|
10
|
+
- '**/.github/**/*.yml'
|
|
11
|
+
- '**/.github/**/*.yaml'
|
|
12
|
+
- '**/.gitlab-ci.yml'
|
|
13
|
+
- '**/.gitlab/**/*.yml'
|
|
14
|
+
- '**/.gitlab/**/*.yaml'
|
|
4
15
|
---
|
|
5
16
|
|
|
17
|
+
Templates, procedures and details: the `lint-npm-yarn` skill.
|
|
18
|
+
|
|
6
19
|
- Prefer using Corepack for all new projects.
|
|
7
20
|
- Prefer Yarn v4+ for all new projects.
|
|
8
21
|
|
|
@@ -27,138 +40,35 @@ description: NPM & Yarn patterns
|
|
|
27
40
|
|
|
28
41
|
# Hoisting
|
|
29
42
|
|
|
30
|
-
- Hoist everything: keep the
|
|
31
|
-
-
|
|
32
|
-
- Electron
|
|
33
|
-
- Binary packagers don't need hoisting limits either: bundle to a single file first, then package — node_modules layout becomes irrelevant; build Node SEA executables with `vp pack` (`exe`, Node ≥ 25.7) when Vite+ is used, else `@yao-pkg/pkg` (maintained fork of the deprecated `vercel/pkg`); a Next.js standalone server cannot be bundled into one file: ship its files as SEA assets and extract them on the first start
|
|
34
|
-
- Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
|
|
35
|
-
- npm / Yarn: default hoisting already exposes them
|
|
36
|
-
- pnpm: add to `.npmrc`: `public-hoist-pattern[]=next`, `public-hoist-pattern[]=tailwindcss`, `public-hoist-pattern[]=storybook`, `public-hoist-pattern[]=jest` (`*eslint*`/`*prettier*` are hoisted by default)
|
|
37
|
-
- Yarn PnP: declare the tools at the workspace root as well
|
|
38
|
-
- If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
43
|
+
- Hoist everything: keep the DEFAULT hoisting of the package manager. Do not set `installConfig.hoistingLimits`, `nmHoistingLimits` or Yarn 1 `nohoist`.
|
|
44
|
+
- Shared root configs (e.g. `@kirill.konshin/lint`) must resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root.
|
|
45
|
+
- Electron, pnpm, binary packagers, "not resolvable from the workspace root": see the `lint-npm-yarn` skill.
|
|
39
46
|
|
|
40
47
|
# Consistent versions
|
|
41
48
|
|
|
42
|
-
In monorepos pin versions of
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
Root `package.json`:
|
|
47
|
-
|
|
48
|
-
```json
|
|
49
|
-
{
|
|
50
|
-
"overrides": {
|
|
51
|
-
"@types/node": "$@types/node",
|
|
52
|
-
"@types/react": "$@types/react",
|
|
53
|
-
"@types/react-dom": "$@types/react-dom",
|
|
54
|
-
"next": "$next",
|
|
55
|
-
"eslint": "$eslint",
|
|
56
|
-
"typescript": "$typescript",
|
|
57
|
-
"vite": "$vite"
|
|
58
|
-
},
|
|
59
|
-
"resolutions": {
|
|
60
|
-
"@types/node": "^26",
|
|
61
|
-
"@types/react": "^19",
|
|
62
|
-
"@types/react-dom": "^19",
|
|
63
|
-
"eslint": "^10",
|
|
64
|
-
"next": "^16",
|
|
65
|
-
"typescript": "^6",
|
|
66
|
-
"vite": "^8"
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
All other `package.json`:
|
|
72
|
-
|
|
73
|
-
```jsonc
|
|
74
|
-
{
|
|
75
|
-
"devDependencies": {
|
|
76
|
-
"next": "^16.0.0", // except next, see nextjs.md
|
|
77
|
-
"typescript": "^6.0.0",
|
|
78
|
-
},
|
|
79
|
-
}
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
Yarn does not apply npm `overrides`; `defineYarnConfig` reads them as constraints together with `resolutions`, keeps non-peer leaf ranges equal, and falls back to the listed default packages when `overrides` is absent.
|
|
83
|
-
|
|
84
|
-
Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
|
|
85
|
-
|
|
86
|
-
```js
|
|
87
|
-
/** @type {import('@yarnpkg/types')} */
|
|
88
|
-
const { defineConfig } = require('@yarnpkg/types');
|
|
89
|
-
const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
|
|
90
|
-
|
|
91
|
-
module.exports = defineConfig(defineYarnConfig());
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
Run `yarn constraints --fix` after dependency changes.
|
|
95
|
-
|
|
96
|
-
# `.yarnrc.yml`
|
|
97
|
-
|
|
98
|
-
Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
|
|
99
|
-
|
|
100
|
-
```yml
|
|
101
|
-
approvedGitRepositories:
|
|
102
|
-
- '**'
|
|
103
|
-
|
|
104
|
-
# print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
|
|
105
|
-
enableInlineBuilds: true
|
|
106
|
-
|
|
107
|
-
enableScripts: true
|
|
108
|
-
|
|
109
|
-
nodeLinker: node-modules
|
|
110
|
-
|
|
111
|
-
npmMinimalAgeGate: 0
|
|
112
|
-
|
|
113
|
-
# own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
|
|
114
|
-
npmPreapprovedPackages:
|
|
115
|
-
- '@kirill.konshin/*'
|
|
116
|
-
```
|
|
49
|
+
- In monorepos, pin the versions of shared packages at the root (`overrides` + `resolutions`). Drift in these versions causes issues.
|
|
50
|
+
- Every package with `"packageManager": "yarn@..."` MUST install `@yarnpkg/types` and use `defineYarnConfig` from `@kirill.konshin/lint/yarn` in `yarn.config.cjs`.
|
|
51
|
+
- Run `yarn constraints --fix` after dependency changes.
|
|
52
|
+
- Do not specify `yarnPath` in `.yarnrc.yml`. Use `packageManager` in `package.json` and Corepack.
|
|
117
53
|
|
|
118
54
|
# Install on CI
|
|
119
55
|
|
|
120
|
-
The single source for CI install rules. Platform steps: github.md, gitlab.md.
|
|
56
|
+
The single source for CI install rules. Platform steps: [github.md](github.md), [gitlab.md](gitlab.md). Shared cache volume and speed-up options: the `lint-npm-yarn` skill.
|
|
121
57
|
|
|
122
58
|
- On CI, set `YARN_ENABLE_GLOBAL_CACHE=false`. Yarn then keeps all packages in `.yarn/cache`, and CI caches this folder.
|
|
123
59
|
- Cache only `.yarn/cache`. NEVER cache `node_modules`: it has too many files to pack and unpack quickly.
|
|
60
|
+
- Exception: the Vite+ task cache `node_modules/.vite/task-cache` (experimental, https://viteplus.dev/guide/github-actions-cache). Measure first. Restore it after install. Use a rolling key `vite-task-<os>-<arch>-<run id>` with a `vite-task-<os>-<arch>-` restore prefix. Do not put sources or lockfiles in the key: Vite Task fingerprints them.
|
|
124
61
|
- IF parallel jobs follow the install, add an `install` job. This job fills the Yarn cache and saves it. The other jobs only read it.
|
|
125
62
|
- IF the pipeline has one job, or its jobs run one after another, do not add an `install` job.
|
|
126
|
-
- Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
|
|
127
|
-
- Set `YARN_ENABLE_GLOBAL_CACHE=true` and put the Yarn global folder on the volume (`YARN_GLOBAL_FOLDER`). Do not use the CI cache for packages.
|
|
128
|
-
- Hardlinks do not cross filesystems. Yarn hardlinks package files from `<globalFolder>/index`. The `node-modules` linker then copies instead and downgrades `nmMode: hardlinks-global` to `hardlinks-local`. The `pnpm` linker has no fallback: it fails with "cross-device link".
|
|
129
|
-
- With Yarn's `nodeLinker: pnpm`, put `pnpmStoreFolder` on the same volume as the global folder, one folder per branch (`/cache/yarn/store/$CI_COMMIT_REF_SLUG`). The link step then takes seconds.
|
|
130
|
-
- Each Yarn `pnpm` install deletes all store entries that it does not use. The per-branch folder keeps installs on other branches away from your store.
|
|
131
|
-
- With pnpm, set `store-dir` on the volume.
|
|
132
|
-
- Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
|
|
133
|
-
- IF `yarn install` is still the CI bottleneck, measure it and evaluate alternatives. The principles of [Speed up NPM/Yarn install in Gitlab](https://www.konshin.org/publications/speed-up-npm-yarn-install-in-gitlab) ([Medium](https://medium.com/disdj/speed-up-npm-yarn-install-in-gitlab-1434437f9857)) still apply. Its tools are outdated.
|
|
134
|
-
- A faster linker: Yarn's `nodeLinker: pnpm` often links faster than `node-modules`, and pnpm is faster still. Both layouts are strict and not hoisted (see Hoisting). Undeclared dependencies fail, and Electron needs a hoisted layout. `@kirill.konshin/lint` is not verified with them.
|
|
135
|
-
- Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
|
|
136
|
-
- A CI image with the dependencies installed
|
|
137
63
|
- IF in doubt, keep `nodeLinker: node-modules`.
|
|
138
64
|
|
|
139
|
-
# Yalc
|
|
140
|
-
|
|
141
|
-
Test unpublished packages in sibling projects (yalc is a root devDependency here):
|
|
142
|
-
|
|
143
|
-
1. `yarn nx run @kirill.konshin/<pkg>:build`
|
|
144
|
-
2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
|
|
145
|
-
3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from this repo)
|
|
146
|
-
|
|
147
|
-
Rules:
|
|
65
|
+
# Yalc
|
|
148
66
|
|
|
149
|
-
- ALWAYS use `yalc link
|
|
150
|
-
-
|
|
151
|
-
-
|
|
152
|
-
- The consumer resolves the linked package's own dependencies from its node_modules — they must be installed there (usually already are as the consumer's own deps)
|
|
153
|
-
- A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
|
|
154
|
-
- Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
|
|
155
|
-
- Yarn 4.17+ quarantines packages published <24h ago (`npmMinimalAgeGate`) — consumers need `npmPreapprovedPackages: ["@kirill.konshin/*"]` in `.yarnrc.yml` to install own packages right after release (older Yarn errors on that key — upgrade the consumer via `packageManager` first)
|
|
156
|
-
- `.yarnrc.local.yml` is NOT a thing (open Yarn feature request, local overrides only via `YARN_*` env vars) and yalc runs NO registry (it is a file store in `~/.yalc`), so a registry override cannot replace linking — `yalc link` is the only mode that leaves all manifests untouched
|
|
67
|
+
- ALWAYS use `yalc link`, NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
|
|
68
|
+
- NEVER commit link artifacts; gitignore `.yalc/` and `yalc.lock` in the consumer
|
|
69
|
+
- Procedure and pitfalls: the `lint-npm-yarn` skill
|
|
157
70
|
|
|
158
|
-
#
|
|
71
|
+
# Publishing
|
|
159
72
|
|
|
160
73
|
- Never bootstrap, publish, or push a release without explicit approval.
|
|
161
|
-
-
|
|
162
|
-
- Configure its GitHub trusted publisher for organization/user `kirill-konshin`, repository `utils`, workflow `release.yml`, optional environment `npm-publish`, and check **Allow npm publish**.
|
|
163
|
-
- Under Publishing access, check **Require two-factor authentication and disallow bypass 2FA tokens (recommended)**; OIDC publishes remain allowed and should be used for every normal release.
|
|
164
|
-
- The first conventional `feat` release establishes the normal `latest` version.
|
|
74
|
+
- First publish of a new package with OIDC: the `lint-npm-yarn` skill.
|
package/rules/nx.md
CHANGED
|
@@ -11,7 +11,7 @@ paths:
|
|
|
11
11
|
|
|
12
12
|
- If NX is used root `package.json` must have `nx show projects > /dev/null` in the `prepare`/`postinstall` script, so the project graph cache exists for tools that read it outside `nx` — e.g. `@nx/eslint-plugin` rules in a bare `eslint` run silently skip without it. With `prepare`, Yarn 2+ skips it on install — run `yarn prepare` explicitly (after cloning + as a CI step); with `postinstall` (private root) Yarn runs it on install, so no extra step
|
|
13
13
|
- With Nx Cloud (`nxCloudId` in `nx.json`) the remote cache replaces CI caching of `.nx/cache` — do NOT cache `.nx` in CI. Set Workspace visibility → Organization members only in the Nx Cloud workspace settings (no anonymous access; fork PRs run without the cache); developers run `npx nx login` once (personal read-write token in the home folder, no env var); CI passes `NX_CLOUD_ACCESS_TOKEN` from repository secrets (environment secrets reach only jobs that declare the environment): a read-write CI access token only on protected branches (`main`, release), a read-only CI access token everywhere else
|
|
14
|
-
- Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see
|
|
14
|
+
- Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see [github.md](github.md) / [gitlab.md](gitlab.md)). One cache entry holds one DB, so restoring several entries does not merge their outputs.
|
|
15
15
|
- NX Release (v23+) with conventional commits silently demotes bumps for `0.x` packages (breaking → minor, `feat` → patch) while the log still claims `Applied semver relative bump "minor"`;
|
|
16
16
|
- set `release.version.adjustSemverBumpsForZeroMajorVersion: false` in `nx.json` if `feat:` must bump minor before `1.0.0`
|
|
17
17
|
- Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with NO `--parallel` flags: parallelism lives in the root `.env` (`NX_PARALLEL=50%` — Nx loads it before every command and parses percentages; `nx.json` `parallel` takes only a number, a string there dispatches nothing); continuous tasks (`start`) always all run, each in its own slot; test runners limit their own workers (Vitest `maxWorkers: '50%'`);
|
package/rules/playwright.md
CHANGED
|
@@ -6,7 +6,7 @@ paths:
|
|
|
6
6
|
- '**/e2e/**'
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
- The apps under test are started outside Playwright, never by its `webServer`: the e2e target `dependsOn` the continuous `start` / `dev` / `serve` targets plus their `wait` probes (`wait-on`), or Docker Compose runs the stack and the suite as a service; see monorepo-turbo-nx.md
|
|
9
|
+
- The apps under test are started outside Playwright, never by its `webServer`: the e2e target `dependsOn` the continuous `start` / `dev` / `serve` targets plus their `wait` probes (`wait-on`), or Docker Compose runs the stack and the suite as a service; see [monorepo-turbo-nx.md](monorepo-turbo-nx.md)
|
|
10
10
|
- The suite reaches the apps through `baseURL` (and other URLs) from the environment, so the same specs run locally, in Compose and against a deployment
|
|
11
11
|
- E2E targets against running apps are `cache: false`; reports and traces (`test-results`, `playwright-report`) are their outputs and CI artifacts
|
|
12
12
|
- How Playwright splits the work:
|
package/rules/react.md
CHANGED
|
@@ -13,12 +13,11 @@ paths:
|
|
|
13
13
|
- `ReactElement<...>` if object-specific
|
|
14
14
|
- If extending functionality of existing component use it's Props:
|
|
15
15
|
- `type DerivedProps = CmpProps & {...}` if `Cmp` provides `CmpProps` (preferred)
|
|
16
|
-
- `type DerivedProps = ComponentProps<typeof Cmp> & {...}` if `Cmp` does provide `CmpProps`
|
|
17
|
-
-
|
|
18
|
-
- Memoize everything
|
|
16
|
+
- `type DerivedProps = ComponentProps<typeof Cmp> & {...}` if `Cmp` does not provide `CmpProps`
|
|
17
|
+
- Memoize components and callbacks unless React Compiler is enabled in the project
|
|
19
18
|
- Prefer `memo<Props>(...)`
|
|
20
19
|
- Use `FC<Props> = memo(...)` if `--isolatedDeclarations` flag is on
|
|
21
|
-
-
|
|
20
|
+
- Wrap callbacks in `useCallback`
|
|
22
21
|
- Prefer to set defaults while destructuring props: `function Cmp({ children = 'xxx' })` where applicable
|
|
23
22
|
|
|
24
23
|
```tsx
|
|
@@ -42,14 +41,14 @@ const containerDefaultProps = SOME_GLOBAL_SETTING ? { ... } : {};
|
|
|
42
41
|
```tsx
|
|
43
42
|
'use client';
|
|
44
43
|
|
|
45
|
-
import { createContext, useContext, useMemo, useState, ReactNode } from 'react';
|
|
44
|
+
import { createContext, useContext, useMemo, useState, Dispatch, ReactNode, SetStateAction } from 'react';
|
|
46
45
|
|
|
47
46
|
// Always type Context explicitly
|
|
48
47
|
// Never export context itself
|
|
49
48
|
const ExampleContext = createContext<{
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
}>(null);
|
|
49
|
+
enabled: boolean;
|
|
50
|
+
setEnabled: Dispatch<SetStateAction<boolean>>;
|
|
51
|
+
} | null>(null);
|
|
53
52
|
|
|
54
53
|
// Export provider
|
|
55
54
|
export function ExampleContextProvider({ children }: { children: ReactNode }) {
|
|
@@ -59,7 +58,7 @@ export function ExampleContextProvider({ children }: { children: ReactNode }) {
|
|
|
59
58
|
// memoize context value
|
|
60
59
|
const value = useMemo(() => ({ enabled, setEnabled }), [enabled, setEnabled]);
|
|
61
60
|
|
|
62
|
-
return <ExampleContext.Provider value={
|
|
61
|
+
return <ExampleContext.Provider value={value}>{children}</ExampleContext.Provider>;
|
|
63
62
|
}
|
|
64
63
|
|
|
65
64
|
// Export hook for consumers
|
package/rules/tailwind.md
CHANGED
|
@@ -1,59 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
type: always_apply
|
|
3
3
|
description: Set of rules for projects which use Tailwind
|
|
4
|
+
paths:
|
|
5
|
+
- '**/*.css'
|
|
6
|
+
- '**/*.tsx'
|
|
4
7
|
---
|
|
5
8
|
|
|
6
|
-
|
|
9
|
+
The `@utility` template and the lint-plugin setup: the `lint-tailwind` skill.
|
|
10
|
+
|
|
11
|
+
- Use Tailwind ONLY for user-facing sites, NEVER for admin — admin interfaces ALWAYS use MUI + `@toolpad/core` (see the `lint-mui` skill)
|
|
7
12
|
- Always use latest version of Tailwind
|
|
8
13
|
- Default UI library for use with Tailwind is Hero UI v3+
|
|
9
14
|
- Use the smallest possible configuration of Tailwind and Hero UI, adhere to their best practices (for Vite, Next.js integration, etc.)
|
|
10
15
|
- Define safe-area insets as named Tailwind utilities; never repeat arbitrary `env(...)` or safe-area calculations in components
|
|
11
16
|
- Safe-area positioning utilities must declare an unconditional design-system gutter first, then enhance it with the maximum of that gutter and the device-reported inset on every edge; use at least `1.5rem` for floating controls because insets can be zero and custom-property resolution can fail on real devices
|
|
12
|
-
|
|
13
|
-
```css
|
|
14
|
-
@utility top-safe {
|
|
15
|
-
top: 1.5rem;
|
|
16
|
-
top: max(1.5rem, env(safe-area-inset-top, 0px));
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
@utility right-safe {
|
|
20
|
-
right: 1.5rem;
|
|
21
|
-
right: max(1.5rem, env(safe-area-inset-right, 0px));
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
@utility bottom-safe {
|
|
25
|
-
bottom: 1.5rem;
|
|
26
|
-
bottom: max(1.5rem, env(safe-area-inset-bottom, 0px));
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
@utility left-safe {
|
|
30
|
-
left: 1.5rem;
|
|
31
|
-
left: max(1.5rem, env(safe-area-inset-left, 0px));
|
|
32
|
-
}
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
# ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
|
|
36
|
-
|
|
37
|
-
- With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; pass `tailwind: { cssConfigPath }` as `vitePlusConfig` options instead of `eslint.config.mjs`
|
|
38
|
-
- The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
|
|
39
|
-
- Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
|
|
40
|
-
- Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
|
|
41
|
-
- `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see npm-yarn.md "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
42
|
-
- Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
|
|
43
|
-
- pass `cssConfigPath` to pick one (if others are not useful) OR
|
|
44
|
-
- create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
|
|
45
|
-
- When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
|
|
46
|
-
- ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
|
|
47
|
-
|
|
48
|
-
```js
|
|
49
|
-
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
50
|
-
|
|
51
|
-
export default defineLintConfig({
|
|
52
|
-
tailwind: {
|
|
53
|
-
cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
|
|
54
|
-
},
|
|
55
|
-
});
|
|
56
|
-
```
|
|
17
|
+
- Lint (eslint-plugin-tailwindcss, also as an Oxlint JS plugin with Vite+) MUST resolve the Tailwind entry CSS, else it crashes; setup: the `lint-tailwind` skill
|
|
57
18
|
|
|
58
19
|
# Hero UI
|
|
59
20
|
|
package/rules/testing.md
CHANGED
|
@@ -12,8 +12,8 @@ paths:
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
14
|
- If project use `vite` or `vite-plus` use `vitest` (`vp test`, imports from `vite-plus/test`), otherwise `jest`
|
|
15
|
-
- With Nx / Turbo, CI runs tests through the orchestrator and its cache (full and affected); the test tool at the root over all projects (`vp test` with `test.projects`, `maxWorkers: '100%'`) is the local full-speed run (see monorepo-turbo-nx.md)
|
|
16
|
-
- If project needs browser-based testing use `playwright`; it splits work over worker processes, test files and `--shard`s (see playwright.md)
|
|
15
|
+
- With Nx / Turbo, CI runs tests through the orchestrator and its cache (full and affected); the test tool at the root over all projects (`vp test` with `test.projects`, `maxWorkers: '100%'`) is the local full-speed run (see [monorepo-turbo-nx.md](monorepo-turbo-nx.md))
|
|
16
|
+
- If project needs browser-based testing use `playwright`; it splits work over worker processes, test files and `--shard`s (see [playwright.md](playwright.md))
|
|
17
17
|
- Suites that need a real server (integration, e2e — Vitest / Jest too): a separate test config and target (e.g. `test:integration` with `vitest.integration.config.ts` over `*.spec.ts`), started by the orchestrator — `dependsOn` the continuous `dev` / `start` plus a `wait` probe, `cache: false` — with a JUnit report; a CI job against an external environment may be allowed to fail, and is not created where its credentials are missing
|
|
18
18
|
- Naming
|
|
19
19
|
- `*.test.ts` for unit tests
|
package/rules/turbo.md
CHANGED
|
@@ -64,7 +64,7 @@ When an app needs a sibling service running in dev (`web` needs `api`), combine:
|
|
|
64
64
|
|
|
65
65
|
- `"with": ["api#start"]` — launches the service alongside, so `turbo run start --filter=web` brings up both (convenience instead of whole-repo `start`)
|
|
66
66
|
- `"dependsOn": ["api#wait"]` — blocks `web#start` until the readiness probe exits
|
|
67
|
-
- Name the probe task `wait` (NOT `dev:ready` as in the Turbo guide) — same task the `^wait` pattern uses (see monorepo-turbo-nx.md)
|
|
67
|
+
- Name the probe task `wait` (NOT `dev:ready` as in the Turbo guide) — same task the `^wait` pattern uses (see [monorepo-turbo-nx.md](monorepo-turbo-nx.md))
|
|
68
68
|
- NEVER put persistent tasks in `dependsOn` — they never exit, so dependents never unblock; depend on the finite `wait` probe
|
|
69
69
|
- `wait` lives in the service package so it self-identifies readiness: `"wait": "wait-on http://localhost:3001/health"` (URL, TCP port, file, socket)
|
|
70
70
|
- Task overrides replace, they don't merge — keep `^wait` when overriding `start`
|