@alxia/create 0.1.2 → 0.1.4

package/README.md

@@ -28,8 +28,8 @@ bun create @alxia my-site --template react-router
 
 | template | what it writes |
 | --- | --- |
-| `api` | an `@alxia/core` app with Zod: `POST /todos` validates its body, behind `requireKey`, a hook made with `defineHook` that answers 401 without an API key; a `bun test` spec calling it with `app.request()` and through `@alxia/client`, typed; `bun dev` restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, a `Dockerfile` on `oven/bun:1`, `.dockerignore`, `.gitignore`, `.env.example` and a README |
-| `react-router` | React Router's official template, as `create-react-router` writes it, shipped in this package and copied, with [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) added as its README says: `alxia()` in `vite.config.ts`'s plugins, `start` running `bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, and a `Dockerfile` on `oven/bun:1` in place of React Router's Node one. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
+| `api` | an `@alxia/core` app with Zod: `POST /todos` validates its body, behind `requireKey`, a hook made with `defineHook` that answers 401 without an API key; a `bun test` spec calling it with `app.request()` and through `@alxia/client`, typed; `bun dev` restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example` and a README |
+| `react-router` | React Router's official template, as `create-react-router` writes it, shipped in this package and copied, with [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) added as its README says: `alxia()` in `vite.config.ts`'s plugins, `start` running `bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, and a `Dockerfile` running on `oven/bun:1-alpine` in place of React Router's Node one. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
 
 The heart of the `api` project, its route and hook (the whole file, with
 its imports and schemas, is in the [guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#the-api-template)):
@@ -53,13 +53,17 @@ export const app = alxia()
 
 ## Docker
 
-Both projects build into an image as they are written, on `oven/bun:1`,
-the image running the app as the non-root `bun` user:
+Both projects build into an image as they are written: built on
+`oven/bun:1`, run on `oven/bun:1-alpine` as the non-root `bun` user, an
+image of about 130 MB. Each `Dockerfile`
+builds in a stage of its own, and the image holds the build output alone,
+no `node_modules`:
 
-- `api`: the production dependencies, then `src/server.ts` run as it is.
-  Bun runs TypeScript, so there is no build stage.
-- `react-router`: the production dependencies, then `bun run build`, then
-  `bun build/server/index.js`.
+- `api`: `bun run build` bundles `src/server.ts` and its dependencies into
+  `dist/server.js`; the image holds `dist/` and runs `bun --no-install dist/server.js`.
+- `react-router`: `bun run build`, every dependency bundled into
+  `build/server/index.js` by `@alxia/react-router`'s plugin; the image
+  holds `build/` and runs `bun --no-install build/server/index.js`.
 
 ```sh
 cd my-api
@@ -76,7 +80,11 @@ docker run -p 3000:3000 my-site
 Commit the `bun.lock` that `bun install` wrote: the image installs from it
 with `--frozen-lockfile`. The
 [guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#docker)
-has the stages.
+has the stages, and
+[troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error-cannot-find-package--from-appdistserverjs)
+what to do for a dependency that cannot be bundled, and for a
+[native addon built for glibc alone](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl),
+which does not load on Alpine.
 
 ## Options
 

package/docs/guide.md

@@ -67,10 +67,10 @@ 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        the production dependencies and src/, on oven/bun:1
+├── 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
@@ -139,12 +139,20 @@ The scripts:
 | `bun dev` | `bun --watch src/server.ts`: restarted on every change, on `PORT` or 3000 |
 | `bun test` | the spec |
 | `bun run typecheck` | `tsc --noEmit` |
-| `bun run build` | `bun build src/server.ts --target=bun --outdir=dist`: one file, its dependencies bundled |
-| `bun start` | `bun src/server.ts`: Bun runs the TypeScript as it is, no build first |
+| `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` |
 
-`build` is for a host that has Bun and no `node_modules`: `dist/server.js`
-holds the dependencies, and runs as `bun dist/server.js`. `start`, `bun dev`
-and the image need no build.
+`start` runs what `build` wrote, as production and the image do:
+
+```sh
+bun run build && bun start
+```
+
+`dist/server.js` holds every dependency, so it runs on a host that has Bun
+and no `node_modules`. It is minified, and `dist/server.js.map` beside it
+is linked from it: Bun reads the map, so a stack trace names the lines of
+`src/`. `bun dev` and `bun test` run the TypeScript as it is, with no
+build.
 
 Bun loads `.env` on every command. `.env.example` names the two variables
 the app reads, `PORT` (3000 by default) and `API_KEY` (`dev-key` by
@@ -222,19 +230,56 @@ goes from there.
 
 ## 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: 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).
+
 ### `api`
 
-Two stages: the production dependencies, installed with
-`bun install --frozen-lockfile --production`, then an image with them,
-`package.json` and `src/`, running `bun src/server.ts`, `start`'s command,
-written out so that Bun is the container's process. There is no build
-stage: Bun runs the TypeScript as it is, so a build would only add a
-second, full install and a bundle the image does not need.
+Two stages: every dependency, installed with
+`bun install --frozen-lockfile`, then `bun run build`, which writes
+`dist/server.js` and its source map; then an image with `dist/` alone,
+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. `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
+WORKDIR /app
+COPY package.json bun.lock* bunfig.toml* ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
+
+FROM oven/bun:1-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/dist ./dist
+USER bun
+EXPOSE 3000
+CMD ["bun", "--no-install", "dist/server.js"]
+```
+
 `.dockerignore` keeps `node_modules`, `dist`, `.env`, the README and the
 specs out of the context.
 
@@ -249,11 +294,15 @@ default is for development.
 
 ### `react-router`
 
-Three stages: the production dependencies, then every dependency and
-`bun run build`, then an image with `build/` and the production
-`node_modules` alone, running `bun build/server/index.js`, `start`'s
-command. `.dockerignore` keeps `node_modules`, `build` and
-`.react-router` out of the context.
+Two stages: every dependency and `bun run build`, then an image with
+`build/` alone, running `bun --no-install build/server/index.js`,
+`start`'s command with `--no-install`.
+`@alxia/react-router`'s plugin bundles every package into
+`build/server/index.js` under `react-router build`, so `build/` needs no
+`node_modules`
+([Self-contained](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md#self-contained)).
+`.dockerignore` keeps `node_modules`, `build` and `.react-router` out of
+the context.
 
 ```sh
 cd my-site

package/docs/roadmap.md

@@ -30,12 +30,26 @@ Nothing scheduled yet.
 
 ### Next release
 
+- **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
+  `dist/server.js` after `bun run build`. The `react-router` template's
+  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` that installs the production
-  dependencies and runs `src/server.ts` as the non-root `bun` user,
-  `.dockerignore`, `.env.example`, and `start` running the source with no
-  build first.
+  a `Dockerfile` on `oven/bun:1`, `.dockerignore` and `.env.example`.
 
 ### 0.1.1
 

package/docs/troubleshooting.md

@@ -36,6 +36,9 @@ nothing — the symptom.
 **After**
 
 - [`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)
 
 ## Before it runs
@@ -242,8 +245,7 @@ project is complete; only `node_modules` is missing.
 ### `error: lockfile had changes, but lockfile is frozen`
 
 **When:** `docker build` in a project stops at
-`RUN bun install --frozen-lockfile` (`react-router`) or
-`RUN bun install --frozen-lockfile --production` (`api`).
+`RUN bun install --frozen-lockfile`.
 
 **Why:** the project's `Dockerfile` installs exactly what `bun.lock`
 records, and `package.json` now asks for something it does not: a
@@ -254,6 +256,105 @@ behind in a clone where `package.json` moved on without it.
 traps of the `react-router` image, a write refused to the `bun` user among them, are in
 [`@alxia/react-router`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#eacces-permission-denied-open-app).
 
+### `error: Module not found "dist/server.js"`
+
+**When:** `bun start` in an `api` project that was never built, or whose
+`dist/` was deleted.
+
+**Why:** `start` runs the build, `bun dist/server.js`, as the image does;
+it no longer runs `src/server.ts`. `bun dev` runs the sources.
+
+**Fix:** build first:
+
+```sh
+bun run build && bun start
+```
+
+### `error: Cannot find package '…' from '/app/dist/server.js'`
+
+The container stops at startup; in the `react-router` image the path is
+`/app/build/server/index.js`. For a package loaded with `require`, Bun
+writes `Cannot find module '…'`. Or the server starts and a request fails
+with `ENOENT: no such file or directory`.
+
+**When:** the image holds the build alone, `dist/` or `build/`, as the
+`Dockerfile` copies it, and a dependency is not inside the bundle: one
+the build was told to leave external, or one that cannot be bundled, a
+native addon (a `.node` file) or a package that reads files of its own
+folder at runtime.
+
+The image runs `bun --no-install`, Bun's flag, not create-alxia's
+option of the same name: without the flag, Bun finds no
+`node_modules` and fetches the missing package from npm at startup, at
+whatever version npm has, instead of failing.
+
+**Why:** the image has no `node_modules`. `bun run build` bundles every
+dependency into one file, and only what it leaves out must be installed
+beside it.
+
+**Fix:** mark the package external, and give the image the production
+dependencies. In `api`, in the `build` script:
+
+```json
+"build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked --external sharp"
+```
+
+In `react-router`, in `vite.config.ts`:
+
+```ts
+export default defineConfig({
+	ssr: { external: ['sharp'] },
+	plugins: [tailwindcss(), reactRouter(), alxia()],
+});
+```
+
+Then in the `Dockerfile`, a stage for the production dependencies, copied
+beside the build:
+
+```dockerfile
+# Before the build stage.
+FROM oven/bun:1 AS production-dependencies
+WORKDIR /app
+COPY package.json bun.lock* bunfig.toml* ./
+RUN bun install --frozen-lockfile --production
+
+# In the final stage, before USER bun.
+COPY --from=production-dependencies /app/node_modules ./node_modules
+```
+
+`grep '^import' dist/server.js` (or `build/server/index.js`) lists what
+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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/create",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"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",
@@ -41,7 +41,7 @@
 	"devDependencies": {
 		"@alxia/client": "^0.2.1",
 		"@alxia/core": "^0.3.1",
-		"@alxia/react-router": "^0.3.0",
+		"@alxia/react-router": "^0.4.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	}

package/templates/api/Dockerfile

@@ -1,22 +1,26 @@
-# Bun runs the app's TypeScript as it is: no build stage, the image holds
-# src/ and the production dependencies. Pinned to Bun 1, the major alxia
-# supports.
+# Bun bundles the app and its dependencies into dist/server.js, and the
+# image holds dist/ alone: no node_modules, no src/. Pinned to Bun 1, the
+# major alxia supports.
 
-# The production dependencies alone, for the final image.
-FROM oven/bun:1 AS production-dependencies
+# Every dependency, then bun run build: dist/server.js and its source map.
+FROM oven/bun:1 AS build
 WORKDIR /app
 COPY package.json bun.lock* bunfig.toml* ./
-RUN bun install --frozen-lockfile --production
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
 
-# The app and its production dependencies, run as Bun's own non-root user
-# with the start script's command, written out so that Bun is the
-# container's process. The server listens on PORT (3000); set API_KEY.
-FROM oven/bun:1
+# The bundle, run as Bun's own non-root user with the start script's
+# 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. 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 package.json ./
-COPY --from=production-dependencies /app/node_modules ./node_modules
-COPY src ./src
+COPY --from=build /app/dist ./dist
 USER bun
 EXPOSE 3000
-CMD ["bun", "src/server.ts"]
+CMD ["bun", "--no-install", "dist/server.js"]

package/templates/api/README.md

@@ -39,21 +39,37 @@ bun run typecheck
 
 ## Build
 
-Bun runs the TypeScript as it is: `bun start` serves `src/server.ts`, with
-no build step. `bun run build` bundles the server and its dependencies into
-one file, for a host with Bun and no `node_modules`:
+`bun run build` bundles the server and its dependencies into one file,
+`dist/server.js`, minified, with its source map beside it, and `bun start`
+runs it: what production and the image run.
 
 ```sh
-bun run build    # dist/server.js
-bun dist/server.js
+bun run build    # dist/server.js and dist/server.js.map
+bun start        # bun dist/server.js
 ```
 
+`bun start` before any build fails with `Module not found
+"dist/server.js"`: build first. `dist/` needs Bun and nothing else, no
+`node_modules`. Bun reads the
+source map, so a stack trace names the lines of `src/`. `bun dev` and
+`bun test` run the TypeScript as it is, with no build.
+
+A dependency that cannot be bundled, a native addon, is left out with
+`--external <name>` in the `build` script, and must then be installed
+beside `dist/`.
+
 ## Docker
 
-The `Dockerfile` installs the production dependencies on `oven/bun:1` and
-runs `src/server.ts` as the image's non-root `bun` user. It installs with
-`--frozen-lockfile`, from the `bun.lock` that `bun install` wrote: commit
-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. `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/package.json

@@ -4,8 +4,8 @@
 	"type": "module",
 	"scripts": {
 		"dev": "bun --watch src/server.ts",
-		"build": "bun build src/server.ts --target=bun --outdir=dist",
-		"start": "bun src/server.ts",
+		"build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
+		"start": "bun dist/server.js",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit"
 	},

package/templates/api/src/server.ts

@@ -1,4 +1,18 @@
 import { app } from './app';
 
+// Stop as the platform asks. In a container Bun is process 1, which a
+// signal with no handler does not stop: `docker stop` would wait.
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+	process.once(signal, () => {
+		void app.stop().then(
+			() => process.exit(0),
+			(error: unknown) => {
+				console.error(error);
+				process.exit(1);
+			},
+		);
+	});
+}
+
 const server = app.listen(Number(Bun.env['PORT'] ?? 3000));
 console.log(`listening on ${server.url}`);

package/templates/react-router/Dockerfile

@@ -1,11 +1,7 @@
-# Bun builds the app and runs it: build/server/index.js is alxia's server,
-# which runs on Bun. Pinned to Bun 1, the major alxia supports.
-
-# The production dependencies alone, for the final image.
-FROM oven/bun:1 AS production-dependencies
-WORKDIR /app
-COPY package.json bun.lock* bunfig.toml* ./
-RUN bun install --frozen-lockfile --production
+# Bun builds the app, and the image holds build/ alone: alxia's plugin
+# bundles every dependency into build/server/index.js, alxia's server, which
+# runs on Bun with no node_modules. Pinned to Bun 1, the major alxia
+# supports.
 
 # Every dependency, then react-router build: build/client and
 # build/server/index.js.
@@ -16,14 +12,17 @@ RUN bun install --frozen-lockfile
 COPY . .
 RUN bun run build
 
-# The build and the production dependencies, run as Bun's own non-root
-# user. The server listens on PORT (3000) and HOST (0.0.0.0).
-FROM oven/bun:1
+# The build, run as Bun's own non-root user with the start script's
+# command, 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) and HOST (0.0.0.0). On Alpine, about
+# 200 MB lighter: build/ 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 package.json ./
-COPY --from=production-dependencies /app/node_modules ./node_modules
 COPY --from=build /app/build ./build
 USER bun
 EXPOSE 3000
-CMD ["bun", "build/server/index.js"]
+CMD ["bun", "--no-install", "build/server/index.js"]

package/templates/react-router/README.md

@@ -66,7 +66,7 @@ The containerized application can be deployed to any platform that supports Dock
 
 ### DIY Deployment
 
-The build is production-ready: `bun run start` runs `build/server/index.js` on Bun.
+The build is production-ready and self-contained: `bun run start` runs `build/server/index.js` on Bun, with every dependency bundled into it, so `build/` needs no `node_modules`.
 
 Make sure to deploy the output of `bun run build`