@activatus/code-standards 3.3.2 โ†’ 3.3.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/README.md CHANGED
@@ -90,6 +90,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
90
90
  - ๐Ÿ—ฃ๏ธ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
91
91
  - ๐Ÿ”’ **Always `const`.** Need `let`? Fine, but leave a comment saying why, or the linter knocks it back.
92
92
  - ๐Ÿน **Arrow functions everywhere.** `const Button = () => {}`. The word `function` is clutter, so we don't use it.
93
+ - ๐Ÿงน **Imports sort themselves.** Prettier puts them in order every time you format, so nobody burns an afternoon shuffling them by hand.
93
94
  - ๐Ÿ”„ **No circular imports. Ever.** If two files import each other, pull the shared bit into a third file.
94
95
  - ๐ŸŽฏ **A function does one thing.** If you need the word "and" to describe it, it's two functions.
95
96
  - ๐Ÿงช **Every function and component gets a test file.** One test file, one thing tested. No test, not finished.
@@ -61,7 +61,7 @@ Applies setup standards 7, 9 and 10. Three commits, in this order:
61
61
  1. **The config files.** Rename every config to `.mjs` ([why](/docs/Guides/setup#5-apply-the-standards)). Add `prettier.config.mjs` from the [Prettier page](/docs/Standards/prettier), with its `format` and `format:check` scripts, `.editorconfig`, `.nvmrc` and `.envrc`. Do not reformat anything yet.
62
62
 
63
63
  ```bash
64
- pnpm add -D prettier prettier-plugin-tailwindcss
64
+ pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
65
65
  ```
66
66
 
67
67
  2. **The reformat, on its own.** Run `pnpm format` and commit the result with nothing else in it. Every file changes, and none of it changes behaviour.
@@ -171,14 +171,14 @@ it makes that the code standards do not cover? Yes or no?
171
171
 
172
172
  Do only the standards the person agreed to. Copy every file from `node_modules/@activatus/code-standards/static/templates/` โ€” never write a config file from scratch.
173
173
 
174
- **Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment, for example `/** @type {import("next").NextConfig} */`. A tool that cannot read `.mjs` keeps its own format.
174
+ **Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment over three lines, `/**`, then `@type {import("next").NextConfig}`, then `*/`, as in the templates. ESLint rejects the one-line form and a `*` at the start of each line. A tool that cannot read `.mjs` keeps its own format.
175
175
 
176
176
  **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
177
177
 
178
178
  | Standard | What to set up |
179
179
  | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
180
180
  | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
181
- | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
181
+ | 7. Prettier | `pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
182
182
  | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
183
183
  | 9. EditorConfig | Copy `static/templates/.editorconfig` |
184
184
  | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
@@ -245,7 +245,9 @@ The project's `next.config.mjs` forwards `/docs` to the docs site, but only when
245
245
  ```js title="next.config.mjs"
246
246
  const DOCS_URL = process.env.DOCS_URL;
247
247
 
248
- /** @type {import("next").NextConfig} */
248
+ /**
249
+ @type {import("next").NextConfig}
250
+ */
249
251
  const nextConfig = {
250
252
  async rewrites() {
251
253
  // The docs are only served when DOCS_URL is set. It is never set in production.
@@ -1091,7 +1091,7 @@ Named exports only. Default exports are allowed where a tool requires them: conf
1091
1091
 
1092
1092
  ### Import order is not linted
1093
1093
 
1094
- There is deliberately no import-**order** rule (circular imports are a different matter โ€” see above). Follow the [Import Organization](/docs/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
1094
+ There is deliberately no import-**order** rule (circular imports are a different matter โ€” see above). Prettier sorts imports instead, every time a file is formatted: see [Import sorting](/docs/Standards/prettier#import-sorting).
1095
1095
 
1096
1096
  ### `unicorn/filename-case: camelCase or PascalCase`
1097
1097
 
@@ -10,7 +10,7 @@ A single shared Prettier config keeps formatting consistent and eliminates "styl
10
10
  ## Installation
11
11
 
12
12
  ```bash
13
- pnpm add -D prettier prettier-plugin-tailwindcss
13
+ pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
14
14
  ```
15
15
 
16
16
  ## Usage
@@ -18,7 +18,9 @@ pnpm add -D prettier prettier-plugin-tailwindcss
18
18
  Create `prettier.config.mjs` in your project root:
19
19
 
20
20
  ```js title="prettier.config.mjs"
21
- /** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
21
+ /**
22
+ @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions}
23
+ */
22
24
  const config = {
23
25
  // Short lines, so code reads well on a phone.
24
26
  printWidth: 70,
@@ -32,7 +34,25 @@ const config = {
32
34
  arrowParens: "always",
33
35
  semi: true,
34
36
  endOfLine: "lf",
35
- plugins: ["prettier-plugin-tailwindcss"],
37
+ // The Tailwind plugin must stay last.
38
+ plugins: [
39
+ "@ianvs/prettier-plugin-sort-imports",
40
+ "prettier-plugin-tailwindcss",
41
+ ],
42
+ // Node's own modules, packages, the project's @/ aliases, then
43
+ // ../ and ./, with a blank line between groups. Side-effect
44
+ // imports, such as CSS, never move.
45
+ importOrder: [
46
+ "<BUILTIN_MODULES>",
47
+ "",
48
+ "<THIRD_PARTY_MODULES>",
49
+ "",
50
+ "^@/",
51
+ "",
52
+ "^[.][.]/",
53
+ "",
54
+ "^[.]/",
55
+ ],
36
56
  tailwindStylesheet: "./app/globals.css",
37
57
  overrides: [
38
58
  {
@@ -97,7 +117,36 @@ The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindl
97
117
 
98
118
  - **It is part of the standard**, not a project extra. Every project that uses Tailwind has it.
99
119
  - **`tailwindStylesheet` points at the project's global stylesheet**, so the plugin knows the project's own colours. Change the path if `globals.css` lives somewhere else.
100
- - **A project with no Tailwind** (a plain Node.js service) removes the `plugins` and `tailwindStylesheet` lines.
120
+ - **A project with no Tailwind** (a plain Node.js service) removes `prettier-plugin-tailwindcss` from `plugins`, and the `tailwindStylesheet` line.
121
+
122
+ ## Import sorting {#import-sorting}
123
+
124
+ The config includes [`@ianvs/prettier-plugin-sort-imports`](https://github.com/IanVS/prettier-plugin-sort-imports). It sorts the imports of every file when the file is formatted, so **nobody sorts imports by hand, and agents never reorder them themselves**: `pnpm format`, or saving in the editor, does it.
125
+
126
+ ```tsx
127
+ "use client";
128
+
129
+ import { readFileSync } from "node:fs";
130
+
131
+ import Link from "next/link";
132
+ import { useState } from "react";
133
+
134
+ import { Button } from "@/components/ui";
135
+ import { r, s } from "@/lib/constants";
136
+
137
+ import { formatDate } from "../utils/formatDate";
138
+
139
+ import type { SampleProps } from "./Sample.types";
140
+
141
+ import "./sample.css";
142
+ ```
143
+
144
+ - **The groups, in order:** Node's own modules (`node:fs`), packages, the project's `@/` aliases, parent folders (`../`), then the same folder (`./`). Each group is alphabetical, with a blank line between groups.
145
+ - **Directives such as `"use client"` stay at the top.**
146
+ - **Side-effect imports never move**, such as `import "./globals.css";`, because the order they load in can matter. The plugin sorts the imports above and below one separately. **Put them after every other import**, so the rest sort as one block. Never add a setting that moves them.
147
+ - **Type imports stay on their own line**, `import type { CardProps } from "./Card.types";`. Leave `importOrderTypeScriptVersion` unset: setting it to 4.5 or above merges type imports into value imports.
148
+ - **`prettier-plugin-tailwindcss` stays last in `plugins`.** The Tailwind plugin needs that to work beside other plugins.
149
+ - **Switching it on reorders the imports in most files.** Do it in a commit of its own, with nothing else in it, so the reordering never hides a real change in a review.
101
150
 
102
151
  ## Settings reference
103
152
 
@@ -31,7 +31,9 @@ Create `stylelint.config.mjs` in your project root:
31
31
  ### Plain CSS and CSS Modules
32
32
 
33
33
  ```js title="stylelint.config.mjs"
34
- /** @type {import("stylelint").Config} */
34
+ /**
35
+ @type {import("stylelint").Config}
36
+ */
35
37
  const config = {
36
38
  ignoreFiles: ["**/vendor/**"],
37
39
  extends: [
@@ -78,7 +80,9 @@ export default config;
78
80
  ### SCSS
79
81
 
80
82
  ```js title="stylelint.config.mjs"
81
- /** @type {import("stylelint").Config} */
83
+ /**
84
+ @type {import("stylelint").Config}
85
+ */
82
86
  const config = {
83
87
  ignoreFiles: ["**/vendor/**"],
84
88
  extends: [
@@ -146,10 +146,11 @@ project-root/
146
146
  | **The site frame** โ€” navigation, header, footer | `components/layout/` | `components/layout/siteHeader/` |
147
147
  | **Three or more pages** of this project | `components/shared/` | `components/shared/pricingTable/` |
148
148
  | **Three or more pages in one section** | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/` |
149
+ | **Three or more pages in a section that already shares a folder** | A `components/` folder in that shared folder | `app/orders/[id]/components/orderSummary/` |
149
150
  | **One or two pages** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
150
151
  | **The homepage** | `app/(homepage)/components/` | `app/(homepage)/components/heroSection/` |
151
152
 
152
- A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`.
153
+ A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`. **A route group is only needed when a section's pages do not already share a folder.** When they all sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and its components go in its own `components/` folder. Never move pages just to make a route group.
153
154
 
154
155
  **The homepage is a route group too: `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/` folders, and is served at `/`. Without it, the homepage's components sit loose in `app/components/` beside the root layout, with no clean place for the next page's. `app/` keeps only the root `layout.tsx` and the files Next.js needs there, such as `globals.css`. A folder inside `app/` is only a route when it holds a `page.tsx` or `route.ts`, so `components/` and `utils/` folders inside `app/` are safe: they never become URLs.
155
156
 
@@ -6,63 +6,62 @@ sidebar_position: 4
6
6
 
7
7
  Consistent import organization makes code easier to read and understand.
8
8
 
9
- ## Import Order
9
+ ## Import order is sorted for you
10
10
 
11
- Follow this order in all files:
11
+ **Prettier sorts the imports of every file** with `@ianvs/prettier-plugin-sort-imports`, the same way it sorts Tailwind classes. Nobody sorts imports by hand, and agents never reorder them themselves: `pnpm format`, or saving in the editor, does it. See [Import sorting](/docs/Standards/prettier#import-sorting).
12
12
 
13
- 1. **React and core packages**
14
- 2. **Internal workspace packages** (the project's own scope, e.g. `@acme/*`)
15
- 3. **External packages**
16
- 4. **Side effect imports**
17
- 5. **Parent imports** (`../`)
18
- 6. **Same-folder imports** (`./`)
19
- 7. **Style imports** (`.css`, `.module.css`)
13
+ ```tsx
14
+ "use client";
20
15
 
21
- ## Example
16
+ import { readFileSync } from "node:fs";
22
17
 
23
- ```tsx
24
- // 1. React and core packages
25
- import React, { useState, useEffect } from "react";
26
- import { Link } from "@radix-ui/react-navigation-menu";
18
+ import Link from "next/link";
19
+ import { useState } from "react";
20
+
21
+ import { Button } from "@/components/ui";
22
+ import { r, s } from "@/lib/constants";
27
23
 
28
- // 2. Internal workspace packages
29
- import { Button } from "@acme/ui";
30
- import { useAuthentication } from "@acme/authentication";
24
+ import { formatDate } from "../utils/formatDate";
31
25
 
32
- // 3. External packages
33
- import { format } from "date-fns";
34
- import clsx from "clsx";
26
+ import type { SampleProps } from "./Sample.types";
35
27
 
36
- // 4. Side effect imports
37
- import "prismjs/themes/prism-tomorrow.css";
28
+ import "./sample.css";
29
+ ```
30
+
31
+ Node's own modules, then packages, the project's `@/` aliases, parent folders (`../`), and the same folder (`./`). **Side-effect imports, such as CSS, go after every other import**: the sorter never moves them, because the order they load in can matter.
38
32
 
39
- // 5. Parent imports
40
- import { formatDate } from "../utils";
33
+ ## Importing components
41
34
 
42
- // 6. Same-folder imports
43
- import { Header } from "./Header";
44
- import { useUserData } from "./useUserData";
35
+ **`components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`**, and code outside a category imports from it, so imports stay short:
45
36
 
46
- // 7. Style imports
47
- import "./UserProfile.css";
48
- import styles from "./styles.module.css";
37
+ ```tsx
38
+ import { Button, Card } from "@/components/ui";
49
39
  ```
50
40
 
51
- ## Why This Order?
41
+ - **No `index.ts` directly in `components/`.** The import shows whether a component is a Design System Component, part of the site frame, or shared.
42
+ - **Inside a category, components import each other by file**, never through the category's own `index.ts`. See [Inside a folder, import files directly](#2-inside-a-folder-import-files-directly).
43
+ - **A category's `index.ts` exports only components a Client Component can import.** A Client Component that imports a category pulls in everything its `index.ts` exports, so one server-only component in it breaks the build for every Client Component that imports the category.
44
+ - **A component that reaches server-only code**, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`. It is left out of its category's `index.ts`, and imported from its own folder:
52
45
 
53
- 1. **React first** - Most important dependency, immediately visible
54
- 2. **Internal packages** - Your team's code, separate from third-party
55
- 3. **External packages** - Third-party dependencies
56
- 4. **Side effects** - Imports that don't export values (CSS, polyfills)
57
- 5. **Parent imports** - Code from parent directories
58
- 6. **Same-folder** - Code from the current directory
59
- 7. **Styles last** - Visual separation, easy to find style imports
46
+ ```tsx
47
+ // components/layout/siteHeader/SiteHeader.tsx
48
+ import "server-only";
60
49
 
61
- ## Rules
50
+ // app/layout.tsx
51
+ import { SiteHeader } from "@/components/layout/siteHeader";
52
+ ```
62
53
 
63
- - โœ… **Alphabetized** within each group
64
- - โœ… **Blank lines** between groups
65
- - โœ… **No duplicates** - Import each module once
54
+ `import "server-only";` makes a mistake fail the build with a clear error, instead of sending server code to the browser.
55
+
56
+ - **Tests mock `server-only`.** Outside a Next.js build, `import "server-only";` always throws, so a Vitest test of the component, or of anything that imports it, fails before it runs. Mock it once in the Vitest setup file, and list that file in `setupFiles` in `vitest.config.mjs`:
57
+
58
+ ```js
59
+ // vitest.setup.mjs
60
+ import { vi } from "vitest";
61
+
62
+ // server-only throws outside a Next.js build.
63
+ vi.mock("server-only", () => ({}));
64
+ ```
66
65
 
67
66
  ## Import Safety
68
67
 
@@ -152,7 +151,3 @@ export const database = createConnection(DATABASE_URL);
152
151
  Code that runs on import makes the order files load in matter. Code that only defines things does not.
153
152
 
154
153
  Enforced by ESLint `unicorn/no-top-level-side-effects`.
155
-
156
- ## Import Order Is Not Enforced
157
-
158
- The **order of the import lines** is a convention, not a lint rule. Follow the same pattern in every file so imports are easy to read, but ESLint will not report an error if the order differs.
@@ -330,7 +330,7 @@ Code files are camelCase or PascalCase. A short list of things are kebab-case in
330
330
  Use ESLint and Prettier to enforce these conventions automatically:
331
331
 
332
332
  - **eslint-plugin-react** - React naming conventions
333
- - **simple-import-sort** - Import ordering
333
+ - **@ianvs/prettier-plugin-sort-imports** - Import ordering, run by Prettier
334
334
  - **@typescript-eslint** - TypeScript naming rules
335
335
 
336
336
  See [ESLint](/docs/Standards/eslint) and [Prettier](/docs/Standards/prettier) configuration for setup.
@@ -60,6 +60,8 @@ Anyone changing the standards adds a version, alongside the change:
60
60
  - **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
61
61
  - **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
62
62
  - **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
63
+ - **Anything a version can change in the `AGENTS.md` template lives between the `code-standards` markers.** A project copies only that section on an update, and `pnpm standards:check` compares only that section, so a rule outside the markers never reaches a project that is already set up.
64
+ - **`pnpm devtest` must pass before publishing.** Run it, then `pnpm publish`. It checks the lint packages are the latest a project would install, then runs the tests, lints every template the way a project does, and checks formatting, types and the site build.
63
65
  - **Every release commit is titled `docs: version N.N.N โ€” <what changed>`**, such as `docs: version 3.2.2 โ€” full version numbers`, so releases are easy to find in the git log.
64
66
  - **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
65
67
  - **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
@@ -68,10 +70,51 @@ Anyone changing the standards adds a version, alongside the change:
68
70
 
69
71
  ## Version 3
70
72
 
71
- **Released:** 2026-10-17 ยท **Updates from:** version 2 ยท **Latest:** 3.3.2
73
+ **Released:** 2026-10-17 ยท **Updates from:** version 2 ยท **Latest:** 3.3.4
72
74
 
73
75
  Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
74
76
 
77
+ **Fixes in 3.3.4.** If the project already applied 3.3.3, check these:
78
+
79
+ - **The config templates now pass the template ESLint config.** `prettier.config.mjs`, `next.config.mjs`, both `stylelint.config.mjs` templates and the regression check's `playwright.config.mjs` started with a one-line `/** @type โ€ฆ */` comment, which `unicorn/single-line-block-comment-style` rejects. They now use a JSDoc comment over three lines, with no `*` at the start of each line, which TypeScript reads the same way. The regression check's `playwright.config.mjs` and `pageLayout.visual.ts` had three more lint errors, now fixed. The code standards now lint every template the way a project does, with the latest lint packages, before every release, so this cannot ship again.
80
+
81
+ **What to do:** copy each of these templates the project uses over its own again: `prettier.config.mjs`, `next.config.mjs`, `stylelint.config.mjs`, and, if the project has a regression check, `tests/visual/playwright.config.mjs` and `tests/visual/pageLayout.visual.ts`. If the project turned a lint rule off for one of them while waiting for this version, remove that from `eslint.overrides.mjs` and from `docs/development/coding-standards.md`.
82
+
83
+ - **Tests mock `server-only`.** `import "server-only";` always throws outside a Next.js build, so any Vitest test that imports a server-only component fails before it runs. See [Importing components](/docs/Structure/import-organization#importing-components).
84
+
85
+ **What to do:** if any file imports `server-only`, add `vi.mock("server-only", () => ({}));` to the Vitest setup file, and make sure `vitest.config.mjs` lists that file in `setupFiles`. Copy the Code standards section of `AGENTS.md` from the template again.
86
+
87
+ **How to check:** `pnpm lint` passes with no rule turned off for a template; `pnpm test` passes; `pnpm standards:check` passes, or lists only recorded exceptions.
88
+
89
+ **Fixes in 3.3.3.** If the project already applied 3.3.2, check these:
90
+
91
+ - **The Ontology and Documentation sections of `AGENTS.md` are now inside the `code-standards` markers.** They were above them, so copying the Code standards section on an update never brought them in, and `pnpm standards:check` never noticed a project without them. 3.3.2's "Record a check only after it has run" rule was one of the rules that never arrived. Anything a version can change now lives inside the markers. The Documentation section's line about `docsSite/` now starts "If the project has a `docsSite/`".
92
+
93
+ **What to do:** copy the Code standards section of `AGENTS.md` from the template again: everything from `<!-- code-standards:start -->` to `<!-- code-standards:end -->`. It now ends with the Ontology and Documentation sections. Then delete the project's old Ontology and Documentation sections above the markers, so neither appears twice. Anything project-specific in them moves to a section of its own, outside the markers.
94
+
95
+ - **A section whose pages already share a folder needs no route group.** When all a section's pages sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and components three or more of its pages use go in its own `components/` folder. Never move pages just to make a route group. See [Where components live](/docs/Structure/folder-structure#-where-components-live). Nothing to do.
96
+ - **Prettier sorts imports.** The Prettier template adds `@ianvs/prettier-plugin-sort-imports`: Node's own modules, then packages, `@/` aliases, `../`, then `./`, with a blank line between groups. Directives such as `"use client"` stay at the top, type imports stay on their own line, and side-effect imports, such as CSS, never move. Nobody sorts imports by hand. The seven-step order on [Import Organization](/docs/Structure/import-organization) is gone. See [Import sorting](/docs/Standards/prettier#import-sorting).
97
+
98
+ **What to do:**
99
+
100
+ 1. `pnpm add -D @ianvs/prettier-plugin-sort-imports`.
101
+ 2. Copy `static/templates/prettier.config.mjs` over the project's again. A project without Tailwind removes `prettier-plugin-tailwindcss` and `tailwindStylesheet` as before.
102
+ 3. Move each side-effect import, such as `import "./globals.css";`, below the file's other imports.
103
+ 4. Run `pnpm format`, and **commit the result on its own**, with nothing else in it, so the reordering never hides a real change in a review.
104
+
105
+ - **Components are imported from their category.** `components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`, and code outside a category imports from it: `import { Button } from "@/components/ui";`. There is no `components/index.ts`, and `pnpm standards:check` now reports one. **A category's `index.ts` exports only components a Client Component can import**: a Client Component that imports a category pulls in everything it exports, so one server-only component in it breaks the build. A component that reaches server-only code, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`, is left out of the `index.ts`, and is imported from its own folder, such as `@/components/layout/siteHeader`. Tested with a Next.js 16 build: the build fails with a server-only component in the category's `index.ts`, and passes once it is imported from its own folder. See [Importing components](/docs/Structure/import-organization#importing-components).
106
+
107
+ **What to do:**
108
+
109
+ 1. Delete any `components/index.ts`, and point its imports at the category: `@/components/ui`, `@/components/layout` or `@/components/shared`.
110
+ 2. Give each category an `index.ts` if it has none.
111
+ 3. For each component that reaches server-only code, add `import "server-only";` at the top, take it out of its category's `index.ts`, and import it from its own folder.
112
+ 4. Copy the Code standards section of `AGENTS.md` from the template again, if not already done for the first fix above.
113
+
114
+ - **"Unfinished changes": write "None", with no note after it.** 3.3.2 said "exactly None", but the check also accepts "None." with a full stop. The template now says what the check does. Nothing to do.
115
+
116
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `AGENTS.md` has one Ontology and one Documentation section, both inside the markers; `pnpm format:check` passes; `git ls-files components/index.ts` finds nothing; no category's `index.ts` exports a file that `grep -rln "server-only" components` lists.
117
+
75
118
  **Fixes in 3.3.2.** If the project already applied 3.3.1, check these:
76
119
 
77
120
  - **Only well-formed lines under "Details" count as exceptions.** `pnpm standards:check` used to read any line under "Details" in `docs/development/coding-standards.md` that started with a number as an exception to that standard, so a plain numbered list switched standards off without a word. Now a line counts only in the shape `N. Name โ€” skipped: reason` or `N. Name โ€” changed: reason`, with the number and name from the [setup list](/docs/Guides/setup#3-agree-the-standards). Any other line that starts with a number fails the check, and a misread line can never be hidden as an exception itself.
@@ -108,7 +151,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
108
151
 
109
152
  - **Record a check only after it has run.** A doc never says a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists. The `AGENTS.md` template, [Docs](/docs/Standards/documentation) and [Regression Checks](/docs/Guides/regression-checks) say so.
110
153
 
111
- **What to do:** read `docs/testing/regression.md` and any other doc that records a check. Remove any result, URL or commit for a check that has not actually run. Copied into `AGENTS.md` with the section above.
154
+ **What to do:** read `docs/testing/regression.md` and any other doc that records a check. Remove any result, URL or commit for a check that has not actually run. Copied into `AGENTS.md` with the section above. _Changed in 3.3.3: the rule was in the template's Documentation section, outside the markers, so copying the section did not bring it in. Do the 3.3.3 step._
112
155
 
113
156
  - **Comparing two local servers: copy `node_modules`, never symlink it.** Turbopack refuses a `node_modules` that points outside the project folder. On macOS, `cp -Rc` makes a copy-on-write clone in seconds. See [Comparing two local servers instead](/docs/Guides/regression-checks#comparing-two-local-servers-instead). Nothing to do.
114
157
  - **"Unfinished changes" says exactly "None" when nothing is left.** A note after it, such as "None. ESLint was switched on in an earlier ticket.", reads as an unfinished change. The template and the check's report now say so.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.3.2",
3
+ "version": "3.3.4",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -34,13 +34,13 @@
34
34
  "@mdx-js/react": "^3.0.0",
35
35
  "clsx": "^2.0.0",
36
36
  "eslint": "^10.13.0",
37
- "eslint-config-next": "^16.4.2",
37
+ "eslint-config-next": "^16.4.3",
38
38
  "eslint-config-prettier": "^10.1.8",
39
39
  "eslint-import-resolver-typescript": "^4.4.5",
40
40
  "eslint-plugin-import-x": "^4.17.1",
41
41
  "eslint-plugin-react": "^7.37.5",
42
42
  "eslint-plugin-react-hooks": "^7.1.1",
43
- "eslint-plugin-unicorn": "^78.0.0",
43
+ "eslint-plugin-unicorn": "^79.0.0",
44
44
  "globals": "^17.13.0",
45
45
  "next": "^16.4.2",
46
46
  "pagefind": "^1.3.0",
@@ -50,7 +50,7 @@
50
50
  "react": "^18.3.1",
51
51
  "react-dom": "^18.3.1",
52
52
  "typescript": "~5.6.2",
53
- "typescript-eslint": "^8.71.2"
53
+ "typescript-eslint": "^8.72.1"
54
54
  },
55
55
  "browserslist": {
56
56
  "production": [
@@ -77,6 +77,7 @@
77
77
  "format": "prettier --write .",
78
78
  "format:check": "prettier --check .",
79
79
  "check:eslint-templates": "node scripts/checkEslintTemplates.mjs",
80
+ "devtest": "node scripts/developmentTest.mjs",
80
81
  "test": "node --test \"scripts/verifyStandards/*.test.mjs\""
81
82
  }
82
83
  }
@@ -13,6 +13,10 @@ const UNGROUPED_HOMEPAGE_PATTERN =
13
13
  const TOP_COMPONENTS_FOLDER_PATTERN =
14
14
  /^((?:src\/)?components\/([^/]+))\//;
15
15
  const COMPONENTS_HOMES = new Set(["ui", "layout", "shared"]);
16
+ // The project's components/ has no index.ts of its own: code imports
17
+ // from a category, "@/components/ui".
18
+ const COMPONENTS_INDEX_PATTERN =
19
+ /^(?:src\/)?components\/index\.(?:ts|tsx|js|jsx)$/;
16
20
  // A component file directly in components/: components/Foo.tsx.
17
21
  const LOOSE_COMPONENT_FILE_PATTERN =
18
22
  /^(?:src\/)?components\/[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
@@ -99,6 +103,16 @@ const checkLooseComponentFolders = ({ projectFiles }) => {
99
103
  }));
100
104
  };
101
105
 
106
+ const checkComponentsIndex = ({ projectFiles }) =>
107
+ projectFiles
108
+ .filter((filePath) => COMPONENTS_INDEX_PATTERN.test(filePath))
109
+ .map((filePath) => ({
110
+ standard: "13",
111
+ file: filePath,
112
+ message: `${filePath} should not exist. Import from a category instead, such as "@/components/ui", and delete it`,
113
+ page: "docs/Structure/import-organization.md#importing-components",
114
+ }));
115
+
102
116
  const checkHomepage = ({ projectFiles }) =>
103
117
  projectFiles
104
118
  .filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
@@ -113,6 +127,7 @@ export const checkStructure = ({ projectFiles }) => {
113
127
  const componentFolders = listComponentFolders({ projectFiles });
114
128
  return [
115
129
  ...checkLooseComponentFolders({ projectFiles }),
130
+ ...checkComponentsIndex({ projectFiles }),
116
131
  ...checkSubComponentFolders({ componentFolders }),
117
132
  ...checkHomepage({ projectFiles }),
118
133
  ];
@@ -80,34 +80,11 @@ Example: `๐ŸŸข [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title
80
80
  | --- | --- | --- |
81
81
  | `[VARIABLE_NAME]` | [Yes / No] | [What it is for] |
82
82
 
83
- ## Ontology
84
-
85
- Activatus uses a fixed vocabulary, the ontology, in two parts:
86
-
87
- - **Code words** โ€” component, utils, Decision Doc and the rest โ€” are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
88
- - **Product words** โ€” what this project builds and how its work is planned โ€” are defined in `docs/product/ontology.md`.
89
-
90
- - **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win โ€” point the difference out.
91
- - **Use their terms** in code, docs, database names and messages โ€” never a synonym. It is `utils`, not `helpers` or `utilities`.
92
- - **Never use a term either ontology has removed.**
93
- - If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
94
-
95
- ## Documentation
96
-
97
- The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
98
-
99
- - **Read them before starting work** โ€” the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
100
- - **Check each doc's Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** โ€” do not treat them as one and do not invent one. Ask.
101
- - **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
102
- - **Record a check only after it has run.** Never write a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists.
103
- - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
104
- - Do not edit `docsSite/` unless the task is about the docs viewer itself.
105
-
106
83
  <!-- code-standards:start -->
107
84
 
108
85
  ## Code standards
109
86
 
110
- **This section is copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
87
+ **This section, and the Ontology and Documentation sections after it, are copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
111
88
 
112
89
  This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
113
90
 
@@ -143,6 +120,8 @@ Follow these rules in every change:
143
120
  - **The linter only checks some names.** Folders, props, form fields, database columns, routes and environment variables are not linted โ€” check every one of them yourself.
144
121
  - **Always `const`.** Never `var`. Use `let` only when a value must be reassigned, with `// eslint-disable-next-line no-restricted-syntax -- <reason>` on the line above.
145
122
  - **Arrow functions everywhere.** Never use the `function` keyword: `export const Button = () => {}`, not `export function Button() {}`.
123
+ - **Never sort imports by hand.** Prettier sorts them on `pnpm format`. Side-effect imports, such as CSS, go after every other import.
124
+ - **Import components from their category:** `import { Button } from "@/components/ui";`. There is no `components/index.ts`. A category's `index.ts` exports only components a Client Component can import: a component that reaches server-only code starts with `import "server-only";`, is left out of it, and is imported from its own folder, such as `@/components/layout/siteHeader`. Tests mock it: `vi.mock("server-only", () => ({}));` in the Vitest setup file.
146
125
  - **No circular imports, ever.** A file never imports a file that imports it back. Inside a folder, import files directly โ€” never through the folder's own `index.ts` โ€” and never import a parent component from its sub-component.
147
126
  - **Define before use.** A function or variable is written above the code that uses it.
148
127
  - **A function does one thing.**
@@ -178,6 +157,29 @@ Follow these rules in every change:
178
157
 
179
158
  When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
180
159
 
160
+ ## Ontology
161
+
162
+ Activatus uses a fixed vocabulary, the ontology, in two parts:
163
+
164
+ - **Code words** โ€” component, utils, Decision Doc and the rest โ€” are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
165
+ - **Product words** โ€” what this project builds and how its work is planned โ€” are defined in `docs/product/ontology.md`.
166
+
167
+ - **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win โ€” point the difference out.
168
+ - **Use their terms** in code, docs, database names and messages โ€” never a synonym. It is `utils`, not `helpers` or `utilities`.
169
+ - **Never use a term either ontology has removed.**
170
+ - If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
171
+
172
+ ## Documentation
173
+
174
+ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
175
+
176
+ - **Read them before starting work** โ€” the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
177
+ - **Check each doc's Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** โ€” do not treat them as one and do not invent one. Ask.
178
+ - **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
179
+ - **Record a check only after it has run.** Never write a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists.
180
+ - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
181
+ - If the project has a `docsSite/`, do not edit it unless the task is about the docs viewer itself.
182
+
181
183
  <!-- code-standards:end -->
182
184
 
183
185
  ## Available skills
@@ -24,7 +24,7 @@ Every Activatus project follows the same standards, so people and agents can mov
24
24
 
25
25
  ## Unfinished changes
26
26
 
27
- [Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write exactly "None", with nothing after it: a note after "None" reads as an unfinished change.]
27
+ [Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write "None", with no note after it: a note after "None" reads as an unfinished change.]
28
28
 
29
29
  ## Related
30
30
 
@@ -1,6 +1,8 @@
1
1
  const DOCS_URL = process.env.DOCS_URL;
2
2
 
3
- /** @type {import("next").NextConfig} */
3
+ /**
4
+ @type {import("next").NextConfig}
5
+ */
4
6
  const nextConfig = {
5
7
  async rewrites() {
6
8
  // The docs are only served when DOCS_URL is set. It is never set in production.
@@ -1,4 +1,6 @@
1
- /** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
1
+ /**
2
+ @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions}
3
+ */
2
4
  const config = {
3
5
  // Short lines, so code reads well on a phone.
4
6
  printWidth: 70,
@@ -12,7 +14,25 @@ const config = {
12
14
  arrowParens: "always",
13
15
  semi: true,
14
16
  endOfLine: "lf",
15
- plugins: ["prettier-plugin-tailwindcss"],
17
+ // The Tailwind plugin must stay last.
18
+ plugins: [
19
+ "@ianvs/prettier-plugin-sort-imports",
20
+ "prettier-plugin-tailwindcss",
21
+ ],
22
+ // Node's own modules, packages, the project's @/ aliases, then
23
+ // ../ and ./, with a blank line between groups. Side-effect
24
+ // imports, such as CSS, never move.
25
+ importOrder: [
26
+ "<BUILTIN_MODULES>",
27
+ "",
28
+ "<THIRD_PARTY_MODULES>",
29
+ "",
30
+ "^@/",
31
+ "",
32
+ "^[.][.]/",
33
+ "",
34
+ "^[.]/",
35
+ ],
16
36
  tailwindStylesheet: "./app/globals.css",
17
37
  overrides: [
18
38
  {
@@ -1,4 +1,6 @@
1
- /** @type {import("stylelint").Config} */
1
+ /**
2
+ @type {import("stylelint").Config}
3
+ */
2
4
  const config = {
3
5
  ignoreFiles: ["**/vendor/**"],
4
6
  extends: [
@@ -1,4 +1,6 @@
1
- /** @type {import("stylelint").Config} */
1
+ /**
2
+ @type {import("stylelint").Config}
3
+ */
2
4
  const config = {
3
5
  ignoreFiles: ["**/vendor/**"],
4
6
  extends: [
@@ -56,9 +56,9 @@ const settlePage = async ({ page }: PageProps) => {
56
56
  for (const animation of finiteAnimations) {
57
57
  animation.finish();
58
58
  }
59
- const images = [...document.images];
60
- await Promise.all(
61
- images.map((image) => image.decode().catch(() => null)),
59
+ // An image that fails to load does not stop the check.
60
+ await Promise.allSettled(
61
+ [...document.images].map((image) => image.decode()),
62
62
  );
63
63
  });
64
64
  };
@@ -8,10 +8,6 @@ import { defineConfig } from "@playwright/test";
8
8
  // test:visual:update.
9
9
  const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
10
10
  const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
11
- // The project's own production build, on a port of its own.
12
- const LOCAL_PORT = 3100;
13
- const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
14
- const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
15
11
 
16
12
  if (isUpdatingBaseline && !PRODUCTION_URL) {
17
13
  throw new Error(
@@ -19,7 +15,14 @@ if (isUpdatingBaseline && !PRODUCTION_URL) {
19
15
  );
20
16
  }
21
17
 
22
- /** @type {import("@playwright/test").PlaywrightTestConfig} */
18
+ // The project's own production build, on a port of its own.
19
+ const LOCAL_PORT = 3100;
20
+ const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
21
+ const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
22
+
23
+ /**
24
+ @type {import("@playwright/test").PlaywrightTestConfig}
25
+ */
23
26
  const config = {
24
27
  testDir: ".",
25
28
  testMatch: "*.visual.ts",