@alxia/create 0.1.2 → 0.1.3

package/README.md

@@ -54,12 +54,15 @@ 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:
+the image running the app as the non-root `bun` user. 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 +79,9 @@ 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.
 
 ## Options
 

package/docs/guide.md

@@ -70,7 +70,7 @@ my-api/
 │   └── server.ts     app.listen(PORT)
 ├── 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
 ├── .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
@@ -227,14 +235,40 @@ image, as the image's non-root `bun` user. 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
+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.
+
+```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
+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 +283,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,16 @@ Nothing scheduled yet.
 
 ### Next release
 
+- **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.
 - **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,8 @@ 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)
 - [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
 
 ## Before it runs
@@ -242,8 +244,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 +255,76 @@ 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.
+
 ### 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.3",
 	"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,24 @@
-# 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.
+# 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.
 FROM oven/bun:1
 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,34 @@ 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`: it
+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.
 
 ```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/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,15 @@ 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).
+# 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).
 FROM oven/bun:1
 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`