@alxia/create 0.1.3 → 0.1.5

package/docs/guide.md

@@ -6,6 +6,7 @@ chooses the versions it writes.
 - [Running it](#running-it)
 - [The `api` template](#the-api-template)
 - [The `react-router` template](#the-react-router-template)
+- [Lint and format](#lint-and-format)
 - [Docker](#docker)
 - [Versions](#versions)
 - [In a script or CI](#in-a-script-or-ci)
@@ -45,7 +46,10 @@ What the command line gives is not asked: `bun create @alxia my-app
 --template react-router` asks nothing. The directory must be empty or not
 exist yet; `.` writes into the current one, when it is empty, and the next
 steps then start at `bun dev`. The package name in `package.json` is the
-directory's name, lowercased, with `-` for anything npm refuses.
+directory's name, lowercased, with `-` for anything npm refuses, and the
+same name replaces the template's own (`my-api`, `my-app`) in its other
+files, as the README's `docker build -t` and `docker run`: `bun create
+@alxia "Mon Super Projet"` writes `mon-super-projet` in both.
 
 `bun create @alxia` is `bunx @alxia/create`: Bun maps `bun create @scope`
 to the package `@scope/create`, and npm maps `npm create @scope` the same
@@ -53,12 +57,15 @@ way. Any of the three runs the same bin, on Bun.
 
 Both templates are files shipped in this package, under
 `templates/api/` and `templates/react-router/`, and copied as they are:
-nothing is downloaded but the dependencies, and only `package.json` is
-written again, with the directory's name, alxia's versions and the newest
-of the others ([Versions](#versions)). Two files are stored under another
-name, since `bun publish` leaves them out of a tarball, and take theirs
-back on the copy: `gitignore` is written as `.gitignore`, `_bunfig.toml`
-as `bunfig.toml`.
+nothing is downloaded but the dependencies. `package.json` is written
+again, with the directory's name, alxia's versions and the newest of the
+others ([Versions](#versions)); in every other text file, the template's
+own name, as a whole word, becomes the project's. Three files are stored
+under another name and take theirs back on the copy: `gitignore` is
+written as `.gitignore` and `_bunfig.toml` as `bunfig.toml`, since `bun
+publish` leaves those out of a tarball, and `_biome.json` as `biome.json`,
+since alxia's own Biome refuses a second root configuration inside its
+repository ([Lint and format](#lint-and-format)).
 
 ## The `api` template
 
@@ -67,10 +74,12 @@ my-api/
 ├── src/
 │   ├── app.ts        the app, and its type
 │   ├── app.spec.ts   bun test: app.request() and @alxia/client
-│   └── server.ts     app.listen(PORT)
+│   └── server.ts     app.listen(PORT), stopped on SIGTERM
 ├── package.json
 ├── tsconfig.json
-├── Dockerfile        bun run build, then dist/ alone, on oven/bun:1
+├── biome.json        Biome: lint, format, imports sorted
+├── .vscode/          Biome's extension recommended, format on save
+├── Dockerfile        bun run build, then dist/ alone, on oven/bun:1-alpine
 ├── .dockerignore
 ├── .env.example      PORT and API_KEY, for a .env Bun loads
 ├── .gitignore
@@ -81,35 +90,35 @@ my-api/
 body validated by a Zod schema, a declared reply, and a hook of its own.
 
 ```ts
-import { alxia, defineHook } from '@alxia/core';
-import { z } from 'zod';
+import { alxia, defineHook } from "@alxia/core";
+import { z } from "zod";
 
 const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
 const NewTodo = z.object({ title: z.string().min(1) });
 
 /** Set API_KEY in the environment: this default is for development. */
-export const apiKey = Bun.env['API_KEY'] ?? 'dev-key';
+export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
 
 const requireKey = defineHook(({ request, reply }) =>
-	request.headers.get('x-api-key') === apiKey
-		? undefined
-		: reply(401, { error: 'unauthorized' as const }),
+  request.headers.get("x-api-key") === apiKey
+    ? undefined
+    : reply(401, { error: "unauthorized" as const }),
 );
 
 const todos: z.infer<typeof Todo>[] = [];
 
 export const app = alxia()
-	.decorate({ todos })
-	.post(
-		'/todos',
-		[requireKey],
-		{ body: NewTodo, response: { 201: Todo } },
-		({ body, todos, reply }) => {
-			const todo = { id: todos.length + 1, title: body.title, done: false };
-			todos.push(todo);
-			return reply.created(todo);
-		},
-	);
+  .decorate({ todos })
+  .post(
+    "/todos",
+    [requireKey],
+    { body: NewTodo, response: { 201: Todo } },
+    ({ body, todos, reply }) => {
+      const todo = { id: todos.length + 1, title: body.title, done: false };
+      todos.push(todo);
+      return reply.created(todo);
+    },
+  );
 
 export type App = typeof app;
 ```
@@ -126,10 +135,10 @@ JSON body, then `@alxia/client` given the app itself, whose result is typed
 by status:
 
 ```ts
-const api = client(app, { headers: { 'x-api-key': apiKey } });
-const created = await api.post('/todos', { body: { title: 'Call it typed' } });
+const api = client(app, { headers: { "x-api-key": apiKey } });
+const created = await api.post("/todos", { body: { title: "Call it typed" } });
 if (created.status !== 201) throw new Error(`got ${created.status}`);
-expect(created.data.title).toBe('Call it typed'); // data is the Todo schema's type
+expect(created.data.title).toBe("Call it typed"); // data is the Todo schema's type
 ```
 
 The scripts:
@@ -141,6 +150,10 @@ The scripts:
 | `bun run typecheck` | `tsc --noEmit` |
 | `bun run build` | `bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked`: one file, its dependencies bundled |
 | `bun start` | `bun dist/server.js`: the build, after `bun run build` |
+| `bun run check` | `biome check --write`: lint, format, sort imports, fixing what it can |
+| `bun run lint`, `bun run format` | `biome lint`, `biome format --write` |
+| `bun run check:ci` | `biome ci`: read-only, for CI |
+| `bun run verify` | `check:ci`, `typecheck`, then `test` |
 
 `start` runs what `build` wrote, as production and the image do:
 
@@ -162,9 +175,10 @@ keeps out of git and `.dockerignore` out of the image.
 `tsconfig.json` holds the settings alxia's own packages are checked under:
 `strict`, and past it `exactOptionalPropertyTypes`,
 `noUncheckedIndexedAccess`, `noPropertyAccessFromIndexSignature`,
-`noUnusedLocals` and the rest. Hence `Bun.env['API_KEY']` and not
-`Bun.env.API_KEY`. Loosen what you would rather not keep: alxia's types
-compile under each one, and under none.
+`noUnusedLocals` and the rest. Hence `Bun.env["API_KEY"]` and not
+`Bun.env.API_KEY`, and Biome's `useLiteralKeys`, which would ask for the
+second, is off in `biome.json`. Loosen what you would rather not keep:
+alxia's types compile under each one, and under none.
 
 ## The `react-router` template
 
@@ -195,6 +209,19 @@ before `bun install`. The change, against React Router's files:
 +  plugins: [tailwindcss(), reactRouter(), alxia()],
 ```
 
+```diff
+ // package.json
+   "scripts": {
++    "lint": "biome lint",
++    "format": "biome format --write",
++    "check": "biome check --write",
++    "check:ci": "biome ci",
++    "verify": "bun run check:ci && bun run typecheck && bun run build"
+   },
+   "devDependencies": {
++    "@biomejs/biome": "2.5.15",
+```
+
 ```toml
 # bunfig.toml, new
 [run]
@@ -204,7 +231,12 @@ bun = true
 ```
 
 The `Dockerfile` is alxia's, in place of React Router's, which builds and
-runs on Node ([Docker](#docker)). Every other file is React Router's:
+runs on Node ([Docker](#docker)). `biome.json` and `.vscode/` are new,
+and the README gains a Lint and format section
+([Lint and format](#lint-and-format)); Biome formatted the scaffold once,
+which changed three of its files: `app/app.css`'s font list wraps
+differently, and `app/routes.ts` and `app/routes/home.tsx` have their
+imports sorted. Every other file is React Router's:
 `app/`, `public/`, `tsconfig.json`, `react-router.config.ts`, its
 `README.md` (with Bun's commands where it wrote npm's: `bun install`,
 `bun dev`, `bun run build`), `.gitignore` and `.dockerignore`. `package.json` takes the directory's name, and its
@@ -228,17 +260,119 @@ bunx alxia-react-router reveal
 The [`@alxia/react-router` guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md)
 goes from there.
 
+## Lint and format
+
+Both projects lint and format with [Biome](https://biomejs.dev), in one
+style whichever template wrote them. Their `biome.json` is a root
+configuration of its own, extending nothing:
+
+```json
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": { "includes": ["**", "!!**/build", "!!**/.react-router"] },
+  "formatter": { "enabled": true, "indentStyle": "space" },
+  "css": { "parser": { "tailwindDirectives": true } },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "correctness": { "noEmptyPattern": "off" }
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": { "source": { "organizeImports": "on" } }
+  },
+  "overrides": [
+    {
+      "includes": ["**/app/welcome/**"],
+      "linter": { "rules": { "a11y": { "noSvgWithoutTitle": "off" } } }
+    }
+  ]
+}
+```
+
+That is the `react-router` project's, written here compact. The `api`
+project's skips `dist/` instead of `build/` and `.react-router/`, has no
+CSS settings and no overrides, and turns `complexity.useLiteralKeys` off
+in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
+
+- **The style is Biome's default but for spaces**: two spaces, double
+  quotes, 80 columns. React Router's scaffold is written so, and so is
+  the `package.json` the command writes: formatting the scaffold once
+  changed three of its files, where tabs would change every line. The
+  `api` project takes the same style, so the two read alike.
+- **`$schema` is the installed Biome's own schema**, so an editor checks
+  the file against the version `bun install` put in `node_modules`,
+  whichever the command wrote.
+- **What is generated is skipped.** `files.includes` leaves `dist/`, or
+  `build/` and `.react-router/`, out, and `vcs.useIgnoreFile` every path
+  `.gitignore` names, the project in a git repository or not (with no
+  `.gitignore` and no git repository, Biome refuses to run:
+  [troubleshooting](troubleshooting.md#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)).
+- **Two rules are off in the `react-router` project, for the scaffold's
+  own code.** `noEmptyPattern`: `meta({}: Route.MetaArgs)` is React
+  Router's idiom for a route module's function that reads none of its
+  arguments. `noSvgWithoutTitle`, under `app/welcome/` alone: the welcome
+  page's logos, which a project replaces.
+- **`css.parser.tailwindDirectives`** lets Biome read Tailwind v4's
+  `@import "tailwindcss"` and `@theme` in `app/app.css`.
+
+`@biomejs/biome` is a devDependency pinned exactly, as Biome recommends,
+since a release may format differently. The command moves it to the
+newest patch of the same minor and keeps it exact: a minor may add a
+recommended rule the template was not checked against
+([Versions](#versions)). To move it later:
+
+```sh
+bun add --dev --exact @biomejs/biome@latest
+bunx biome migrate --write
+```
+
+| script | runs |
+| --- | --- |
+| `bun run check` | `biome check --write`: lint, format and sort imports, fixing what it can |
+| `bun run lint` | `biome lint` |
+| `bun run format` | `biome format --write` |
+| `bun run check:ci` | `biome ci`: changes nothing, and fails on any error |
+| `bun run verify` | `check:ci`, `typecheck`, then `test` (`api`) or `build` (`react-router`) |
+
+The read-only one is `check:ci`, not `ci`: `bun ci` is Bun's
+`bun install --frozen-lockfile`, and a script named `ci` would only run
+as `bun run ci`. A CI job runs:
+
+```sh
+bun install --frozen-lockfile
+bun run verify
+```
+
+`.vscode/extensions.json` recommends Biome's extension, `biomejs.biome`,
+and `.vscode/settings.json` makes it the default formatter, formatting on
+save. Another editor reads `biome.json` through Biome's own extension for
+it.
+
 ## Docker
 
-Each project's `Dockerfile` runs it on Bun, on the official `oven/bun:1`
-image, as the image's non-root `bun` user. The installs are
+Each project's `Dockerfile` builds it on Bun's official `oven/bun:1`
+image, Debian's, and runs it on `oven/bun:1-alpine`, as that image's
+non-root `bun` user (uid 1000). The installs are
 `--frozen-lockfile`, from the `bun.lock` the command's `bun install`
 wrote: commit it.
 
 Each one builds in a stage of its own, and the image holds the build
 output alone: no `node_modules`, no sources. The dependencies are inside
 the bundle, so the image is the base image and a few hundred kilobytes to
-a few megabytes. A dependency that cannot be bundled is kept external and
+a few megabytes: about 130 MB, where the same build on `oven/bun:1` is
+about 345 MB.
+
+The build stages stay on Debian: the tools a build runs, Vite's,
+Tailwind's and any package's install script, are tried on glibc first,
+and Alpine saves nothing there, since the stage is not shipped. What is
+shipped is JavaScript, which Bun runs the same on musl. A native addon is
+the exception: one built for glibc alone cannot load on Alpine, and the
+final stage goes back to `oven/bun:1`
+([troubleshooting](troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)). A dependency that cannot be bundled is kept external and
 copied in: see
 [troubleshooting](troubleshooting.md#error-cannot-find-package--from-appdistserverjs).
 
@@ -250,7 +384,8 @@ Two stages: every dependency, installed with
 running `bun --no-install dist/server.js`, `start`'s command with
 Bun's `--no-install` (not create-alxia's option of the same name), so that a package missing from the bundle fails at
 startup rather than being fetched from npm, written out so that Bun
-is the container's process.
+is the container's process. `src/server.ts` stops the app on `SIGTERM`:
+as process 1, Bun would otherwise ignore it, and `docker stop` would wait.
 
 ```dockerfile
 FROM oven/bun:1 AS build
@@ -260,7 +395,7 @@ RUN bun install --frozen-lockfile
 COPY . .
 RUN bun run build
 
-FROM oven/bun:1
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/dist ./dist
@@ -308,7 +443,8 @@ are in
 A template ships the versions it was generated with, and React Router's
 lags behind its own releases. So before installing, the command
 asks the registry for every dependency's versions, and writes `^` the
-newest one alxia accepts:
+newest one alxia accepts, or the version alone for a dependency the
+template pins exactly:
 
 | dependency | moved to the newest within |
 | --- | --- |
@@ -317,6 +453,7 @@ newest one alxia accepts:
 | `zod` | `^4.2.0`, `@alxia/zod`'s |
 | `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
 | `react-router`, `@react-router/*` | `^8.0.0`, `@alxia/react-router`'s; the `@react-router/*` packages take `react-router`'s version, which `@react-router/node` pins exactly |
+| `@biomejs/biome` | its own minor, from the exact version the template pins (`~2.5.15`): written exactly, `2.5.16`, never `^` |
 | anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
 
 The command prints each move, and each newer major it left out:

package/docs/roadmap.md

@@ -30,6 +30,26 @@ Nothing scheduled yet.
 
 ### Next release
 
+- **Both projects lint and format with Biome.** Each has a `biome.json`
+  of its own (recommended rules, spaces and double quotes, imports
+  sorted, the build output skipped), `@biomejs/biome` pinned exactly,
+  the scripts `lint`, `format`, `check`, `check:ci` and `verify`, and
+  `.vscode/` recommending Biome's extension. A new project passes
+  `bun run check:ci` with no finding.
+- **The project's name in its README.** The name given to the command,
+  normalised, replaces the template's own, as a whole word, in every text
+  file, as the README's
+  `docker build -t` and `docker run`.
+
+### 0.1.4
+
+- **The images run on Alpine.** Every `Dockerfile`'s final stage is
+  `oven/bun:1-alpine`, the build stages staying on `oven/bun:1`: each
+  image is about 130 MB, where it was about 345 MB. The `api` project
+  stops on `SIGTERM`, so `docker stop` no longer waits.
+
+### 0.1.3
+
 - **Every `Dockerfile` builds, and the image holds the build alone.** The
   `api` template's builds `dist/server.js`, bundled, minified and source
   mapped, and runs it with no `node_modules` and no `src/`; `start` runs
@@ -37,6 +57,9 @@ Nothing scheduled yet.
   copies `build/` alone, which `@alxia/react-router`'s plugin now bundles
   whole. Each image is about 50 MB (api) and 150 MB (react-router)
   smaller.
+
+### 0.1.2
+
 - **The `api` template is files, copied, with a `Dockerfile`.** It ships
   under `templates/api/` and is copied as `react-router`'s is. New in it:
   a `Dockerfile` on `oven/bun:1`, `.dockerignore` and `.env.example`.

package/docs/troubleshooting.md

@@ -38,8 +38,15 @@ nothing — the symptom.
 - [`error: lockfile had changes, but lockfile is frozen`](#error-lockfile-had-changes-but-lockfile-is-frozen)
 - [`error: Module not found "dist/server.js"`](#error-module-not-found-distserverjs)
 - [`error: Cannot find package '…' from '/app/dist/server.js'`](#error-cannot-find-package--from-appdistserverjs)
+- [`error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`](#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)
 - [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
 
+**Biome**
+
+- [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
+- [`× Found a nested root configuration, but there's already a root configuration.`](#-found-a-nested-root-configuration-but-theres-already-a-root-configuration)
+- [`× Biome couldn't find an ignore file in the following folder: …`](#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)
+
 ## Before it runs
 
 ### `error: GET https://registry.npmjs.org/@alxia%2fcreate - 404`
@@ -325,6 +332,35 @@ COPY --from=production-dependencies /app/node_modules ./node_modules
 the bundle still imports: Node's and Bun's modules, and the packages left
 external.
 
+### `error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`
+
+The container stops at startup, or at the first request that loads the
+package, with the path of a `.node` file in `node_modules` and
+`code: "ERR_DLOPEN_FAILED"`. The library named after `DT_NEEDED` is
+whichever one the addon links first: `libc.so.6`, `libstdc++.so.6` or
+another; the fix is the same.
+
+**When:** a package is kept external and installed beside the build, as
+the previous entry says, and it loads a native addon built for glibc
+alone.
+
+**Why:** the final stage is `oven/bun:1-alpine`, whose C library is
+musl. The bundle is JavaScript, which runs the same there, but a `.node`
+file is compiled against one C library, and one compiled for glibc
+cannot load on musl, even with `gcompat`. A package that publishes a
+musl build too, as `sharp` does, works: `bun install`, `--production` too,
+puts both variants in `node_modules`, and the package picks musl's.
+
+**Fix:** run the final stage on Debian's image, `oven/bun:1`, which
+holds glibc. The build stages stay as they are:
+
+```dockerfile
+# The final stage.
+FROM oven/bun:1
+```
+
+The image is about 200 MB larger.
+
 ### The project's `@alxia/*` are older than npm's latest
 
 **Symptom:** a fresh project declares `@alxia/core` at `^0.3.4` while npm
@@ -342,3 +378,64 @@ an existing project
 `bun add @alxia/core@latest @alxia/react-router@latest` (`react-router`), reading
 [`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
 for what a minor changed.
+
+## Biome
+
+### `bun ci` installs, and checks nothing
+
+**Symptom:** `bun ci` in a project prints an install, `bun install
+v1.4.2`, and no Biome output; a CI step meant to lint passes whatever the
+code.
+
+**Why:** `bun ci` is Bun's own command, `bun install --frozen-lockfile`,
+and a command Bun knows wins over a script. The projects name their
+read-only check `check:ci` for that reason
+([Lint and format](guide.md#lint-and-format)).
+
+**Fix:** run the script by `bun run`:
+
+```sh
+bun run check:ci   # biome ci alone
+bun run verify     # biome ci, typecheck, then test or build
+```
+
+### `× Found a nested root configuration, but there's already a root configuration.`
+
+**When:** Biome runs from a folder above the project that has its own
+`biome.json`: the project was created inside a monorepo, and `biome ci`
+runs from the monorepo's root.
+
+**Why:** the project's `biome.json` is a root configuration, so that it
+works on its own. Biome takes one root per run; a configuration below it
+must say it is nested.
+
+**Fix:** to keep the monorepo's settings and add the project's, make the
+project's nested, at the top of its `biome.json`:
+
+```json
+{
+  "root": false,
+  "extends": "//",
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json"
+}
+```
+
+and keep the rest of the file. `"extends": "//"` takes the root's
+settings, which the project's own override. To use the monorepo's
+settings alone, delete the project's `biome.json` and its
+`@biomejs/biome`.
+
+### `× Biome couldn't find an ignore file in the following folder: …`
+
+**When:** `bun run check:ci`, `check`, `lint` or `format` in a project
+with no `.gitignore`, deleted or renamed, and outside any git repository.
+Inside one, Biome reads git's ignore rules and runs.
+
+**Why:** `biome.json` sets `vcs.useIgnoreFile`, which skips what
+`.gitignore` names. Inside a git repository Biome falls back on git's
+own ignore rules; with no `.gitignore` and no repository, it refuses to
+run rather than skip nothing.
+
+**Fix:** put a `.gitignore` back, even an empty one, or set
+`"useIgnoreFile": false` in `biome.json`'s `vcs`: `files.includes` still
+skips the build output.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/create",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
 	"license": "MIT",
 	"type": "module",

package/templates/api/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["biomejs.biome"]
+}

package/templates/api/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  }
+}

package/templates/api/Dockerfile

@@ -14,8 +14,10 @@ RUN bun run build
 # command, written out so that Bun is the container's process, and
 # --no-install: with no node_modules, Bun would otherwise fetch a package
 # the build left out from the registry at startup, where this fails. The
-# server listens on PORT (3000); set API_KEY.
-FROM oven/bun:1
+# server listens on PORT (3000); set API_KEY. On Alpine, about 200 MB
+# lighter: the bundle is JavaScript, which runs the same on musl. A native
+# addon built for glibc alone needs oven/bun:1 here.
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/dist ./dist

package/templates/api/README.md

@@ -7,6 +7,7 @@ An [alxia](https://github.com/softistx/alxia) app with
   its own hook, `requireKey`, answers 401 without the `x-api-key` header.
 - `src/server.ts`: listens on `PORT`, 3000 by default.
 - `src/app.spec.ts`: `app.request()` and `@alxia/client`, no port.
+- `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
 
 ## Environment
 
@@ -37,6 +38,32 @@ bun test         # src/app.spec.ts: in process, and through the typed client
 bun run typecheck
 ```
 
+## Lint and format
+
+[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
+sets it: Biome's recommended rules, spaces, double quotes, imports
+sorted. What the build writes, `dist/`, is skipped.
+
+```sh
+bun run check      # lint, format and sort imports, fixing what it can
+bun run lint       # lint only
+bun run format     # format only, in place
+bun run check:ci   # what CI runs: changes nothing, fails on an error
+bun run verify     # check:ci, then typecheck, then test
+```
+
+`bun run check:ci`, not `bun ci`: `bun ci` is Bun's frozen-lockfile
+install. In VS Code, `.vscode/` recommends Biome's extension and formats
+on save with it.
+
+`@biomejs/biome` is pinned exactly, since a release of Biome may format
+differently. To move it:
+
+```sh
+bun add --dev --exact @biomejs/biome@latest
+bunx biome migrate --write
+```
+
 ## Build
 
 `bun run build` bundles the server and its dependencies into one file,
@@ -60,13 +87,16 @@ beside `dist/`.
 
 ## Docker
 
-The `Dockerfile` builds in a stage of its own, on `oven/bun:1`: it
+The `Dockerfile` builds in a stage of its own, on `oven/bun:1`, and runs
+on `oven/bun:1-alpine`. The build stage
 installs every dependency with `--frozen-lockfile`, from the `bun.lock`
 that `bun install` wrote (commit it), and runs `bun run build`. The image
 holds `dist/` alone, no `node_modules` and no `src/`, and runs
 `bun --no-install dist/server.js` as its non-root `bun` user: a package
 missing from the bundle fails at startup instead of being fetched from
-npm.
+npm. `src/server.ts` stops the app on `SIGTERM`, so `docker stop` is
+immediate. A native addon built for glibc alone does not load on
+Alpine: put the final stage back on `oven/bun:1`.
 
 ```sh
 docker build -t my-api .

package/templates/api/_biome.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!!**/dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "complexity": {
+        "useLiteralKeys": "off"
+      }
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}