@alxia/create 0.1.0 → 0.1.2

package/docs/troubleshooting.md

@@ -26,17 +26,16 @@ nothing — the symptom.
 
 **Writing the project**
 
-- [`create-alxia: create-react-router's … is not what this @alxia/create expects: …`](#create-alxia-create-react-routers--is-not-what-this-alxiacreate-expects-)
-- [`create-alxia: failed: create-react-router exited with 1.`](#create-alxia-failed-create-react-router-exited-with-1)
 - [`create-alxia: failed: …`](#create-alxia-failed-)
 - [`create-alxia: warning: the registry did not answer for …; kept the versions the template ships.`](#create-alxia-warning-the-registry-did-not-answer-for--kept-the-versions-the-template-ships)
 - [`typescript: kept to ^6.0.3 || ^7.0.0, where the newest is 7.0.2; npm's latest, 8.0.0, is outside it`](#typescript-kept-to-603--700-where-the-newest-is-702-npms-latest-800-is-outside-it)
 - [`zod: no release within ^4.2.0; kept ^4.2.0`](#zod-no-release-within-420-kept-420)
+- [`@alxia/core: the registry has no release within ^0.3.1 yet; wrote ^0.3.0, the newest of ~0.3.0`](#alxiacore-the-registry-has-no-release-within-031-yet-wrote-030-the-newest-of-030)
 - [`create-alxia: bun install failed; the files are written.`](#create-alxia-bun-install-failed-the-files-are-written)
 
 **After**
 
-- [The `react-router` project's `docker build` fails](#the-react-router-projects-docker-build-fails)
+- [`error: lockfile had changes, but lockfile is frozen`](#error-lockfile-had-changes-but-lockfile-is-frozen)
 - [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
 
 ## Before it runs
@@ -148,47 +147,6 @@ project beside it and move the files in.
 
 ## Writing the project
 
-### `create-alxia: create-react-router's … is not what this @alxia/create expects: …`
-
-**When:** the `react-router` template, after `create-react-router` ran.
-The message names the file — `package.json`, `vite.config.ts` or
-`bunfig.toml` — and what was expected of it:
-
-- `it is missing`: no `package.json` or `vite.config.ts`;
-- `react-router in its dependencies, and the scripts dev: react-router dev, build: react-router build and a start`;
-- `reactRouter() from "@react-router/dev/vite", called once in plugins: [...]`;
-- `it already imports @alxia/react-router/vite`;
-- `none, and there is one`: a `bunfig.toml` already.
-
-**Why:** React Router's template changed since this `@alxia/create` was
-released, and the edits that add alxia check each file before changing it
-rather than write a project that does not start. What was written is
-removed: the target directory is emptied when it was there, removed when
-it was not. A parent directory the command created for it, as `a/b` for
-`a/b/my-site`, stays.
-
-**Fix:** run the newest `@alxia/create`, whose edits follow the newest
-template:
-
-```sh
-bunx @alxia/create@latest my-site --template react-router
-```
-
-If that one refuses too, add alxia to React Router's template by hand, as
-[`@alxia/react-router`'s README](https://www.npmjs.com/package/@alxia/react-router)
-shows (`bun add`, `alxia()` in `vite.config.ts`, `start`), and open an
-issue.
-
-### `create-alxia: failed: create-react-router exited with 1.`
-
-**When:** the `react-router` template, when `create-react-router` itself
-failed; its own output, just above, says why. Most often the network:
-`bunx` could not fetch it, or it could not fetch React Router's template
-from GitHub.
-
-**Fix:** what its output says, then run the command again: what was
-written is removed.
-
 ### `create-alxia: failed: …`
 
 **When:** any other error while writing the project, with the error's own
@@ -196,7 +154,22 @@ message after `failed:` — most often the file system: `EACCES` writing
 into a directory the user cannot write to, `ENOSPC` with the disk full.
 
 **Fix:** what the message names, then run the command again: what was
-written is removed, as above.
+written is removed — the target directory is emptied when it was there,
+removed when it was not. A parent directory the command created for it, as
+`a/b` for `a/b/my-site`, stays.
+
+### `create-alxia: failed: the api template names @alxia/zod at workspace:, which this @alxia/create has no version for`
+
+**When:** at once, before anything is written; the template and package
+vary.
+
+**Why:** a template names an `@alxia/*` package at `workspace:^`, which
+the command replaces with the version it was published beside, and this
+release has none for that package. It is a broken `@alxia/create`
+release, not your setup.
+
+**Fix:** run the previous release, `bunx @alxia/create@<version>`, and
+report it on [GitHub](https://github.com/softistx/alxia/issues).
 
 ### `create-alxia: warning: the registry did not answer for …; kept the versions the template ships.`
 
@@ -211,7 +184,10 @@ that is React Router's, whose TypeScript may be older than alxia accepts.
 
 **Fix:** once the registry answers, run the command again in an empty
 directory, or move the packages named within alxia's ranges by hand:
-`bun add -d typescript@^7 vite@^8`. Behind a proxy, check `BUN_CONFIG_REGISTRY` or
+`bun add -d typescript@^7 vite@^8`. The message can name an `@alxia/*`
+package too, on a mirror that does not hold alxia's: the range kept is the
+one this `@alxia/create` was published with, which that mirror cannot
+install either, so let it proxy npmjs.org. Behind a proxy, check `BUN_CONFIG_REGISTRY` or
 `npm_config_registry`, which the command reads.
 
 ### `typescript: kept to ^6.0.3 || ^7.0.0, where the newest is 7.0.2; npm's latest, 8.0.0, is outside it`
@@ -231,11 +207,27 @@ once the major is tested, and the next `@alxia/create` takes it.
 **When:** a notice: the registry answered for the package, but none of its
 releases is in the range alxia's packages accept — a registry mirror that
 holds only some versions, most often. The template's own version is kept.
+An `@alxia/*` package prints it too when the registry holds none of the
+range's minor, not even an older patch.
 
 **Fix:** check what the registry holds (`bun pm view zod versions`), let
 the mirror fetch the missing ones, or write a version within the range by
 hand after the project is created.
 
+### `@alxia/core: the registry has no release within ^0.3.1 yet; wrote ^0.3.0, the newest of ~0.3.0`
+
+**When:** a notice, not an error, right after an alxia release: the
+registry lists `@alxia/create`'s new version but not yet the
+`@alxia/core` (or `@alxia/client`, `@alxia/react-router`) published beside
+it. npm can take a few minutes to serve a version everywhere.
+
+**Why:** a project written with `^0.3.1` would fail its `bun install` with
+`No version matching "^0.3.1" found`. The command writes the newest release
+of the same minor instead; `^0.3.0` still takes 0.3.1.
+
+**Fix:** nothing to do. Once the registry serves the new version,
+`bun update @alxia/core` moves the project to it.
+
 ### `create-alxia: bun install failed; the files are written.`
 
 **When:** `bun install` exited non-zero in the new project; its output,
@@ -247,32 +239,35 @@ project is complete; only `node_modules` is missing.
 
 ## After
 
-### The `react-router` project's `docker build` fails
+### `error: lockfile had changes, but lockfile is frozen`
 
-**Symptom:** `COPY ./package.json package-lock.json /app/` finds no
-`package-lock.json`, or the image starts and `bun: not found`.
+**When:** `docker build` in a project stops at
+`RUN bun install --frozen-lockfile` (`react-router`) or
+`RUN bun install --frozen-lockfile --production` (`api`).
 
-**Why:** React Router's `Dockerfile` is kept as its template writes it: on
-Node, installed with npm. Once `start` runs `bun build/server/index.js`,
-it no longer fits.
+**Why:** the project's `Dockerfile` installs exactly what `bun.lock`
+records, and `package.json` now asks for something it does not: a
+dependency added or changed by hand, without `bun install`, or a `bun.lock` left
+behind in a clone where `package.json` moved on without it.
 
-**Fix:** base it on an `oven/bun` image, install with
-`bun install --production`, and make its command
-`bun build/server/index.js`, as
-[`@alxia/react-router`'s guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md#deploying)
-says.
+**Fix:** run `bun install`, commit `bun.lock`, and build again. The other
+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).
 
 ### The project's `@alxia/*` are older than npm's latest
 
-**Symptom:** a fresh project declares `@alxia/core` at `^0.3.0` while npm
-has `0.4.0`.
+**Symptom:** a fresh project declares `@alxia/core` at `^0.3.4` while npm
+has `0.4.0`, and the output said `@alxia/core: kept to ^0.3.1, where the
+newest is 0.3.4; npm's latest, 0.4.0, is outside it`.
 
-**Why:** alxia's packages are written at the versions the `@alxia/create`
-that ran was published with ([Versions](guide.md#versions)), and a release
-of `@alxia/core` alone does not release a new `@alxia/create`.
+**Why:** alxia's packages move only within the ranges the `@alxia/create`
+that ran was published with ([Versions](guide.md#versions)): a new minor
+is outside them, and a release of `@alxia/core` alone does not release a
+new `@alxia/create`.
 
 **Fix:** `bunx @alxia/create@latest` for the newest `@alxia/create`, and in
 an existing project
-`bun add @alxia/core@latest @alxia/client@latest`, reading
+`bun add @alxia/core@latest @alxia/client@latest` (`api`) or
+`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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/create",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"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",
@@ -10,6 +10,8 @@
 	"files": [
 		"dist",
 		"docs",
+		"templates/api",
+		"templates/react-router",
 		"README.md",
 		"package.json",
 		"LICENSE"
@@ -28,7 +30,7 @@
 	},
 	"scripts": {
 		"build": "bun run ../../build.ts",
-		"test": "bun test src",
+		"test": "bun test ./src",
 		"typecheck": "tsc --noEmit"
 	},
 	"alxia": {
@@ -39,7 +41,7 @@
 	"devDependencies": {
 		"@alxia/client": "^0.2.1",
 		"@alxia/core": "^0.3.1",
-		"@alxia/react-router": "^0.2.0",
+		"@alxia/react-router": "^0.3.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	}

package/templates/api/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.local
+README.md
+**/*.spec.ts

package/templates/api/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env, which Bun loads on every command: bun dev, bun test, bun start.
+PORT=3000
+API_KEY=dev-key

package/templates/api/Dockerfile

@@ -0,0 +1,22 @@
+# 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.
+
+# 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
+
+# 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
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json ./
+COPY --from=production-dependencies /app/node_modules ./node_modules
+COPY src ./src
+USER bun
+EXPOSE 3000
+CMD ["bun", "src/server.ts"]

package/templates/api/README.md

@@ -0,0 +1,64 @@
+# An alxia API
+
+An [alxia](https://github.com/softistx/alxia) app with
+[Zod](https://zod.dev), made with `bun create @alxia`.
+
+- `src/app.ts`: the app. `POST /todos` validates its body with Zod, and
+  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.
+
+## Environment
+
+Bun loads `.env` on every command. Copy `.env.example` to `.env` to set
+`PORT` and `API_KEY`. Outside development, set `API_KEY`: its default,
+`dev-key`, is for development only.
+
+```sh
+cp .env.example .env
+```
+
+## Develop
+
+```sh
+bun dev          # http://localhost:3000, restarted on every change
+```
+
+```sh
+curl -X POST localhost:3000/todos \
+  -H 'content-type: application/json' -H 'x-api-key: dev-key' \
+  -d '{"title":"Write a route"}'
+```
+
+## Test
+
+```sh
+bun test         # src/app.spec.ts: in process, and through the typed client
+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`:
+
+```sh
+bun run build    # dist/server.js
+bun dist/server.js
+```
+
+## 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.
+
+```sh
+docker build -t my-api .
+docker run --rm -p 3000:3000 -e API_KEY=change-me my-api
+```
+
+Next: [Getting started](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/getting-started.md)
+and the rest of [`@alxia/core`'s guide](https://github.com/softistx/alxia/tree/develop/packages/core/docs).

package/templates/api/gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+*.log
+.DS_Store
+.env
+.env.local

package/templates/api/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "my-api",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "bun --watch src/server.ts",
+		"build": "bun build src/server.ts --target=bun --outdir=dist",
+		"start": "bun src/server.ts",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@alxia/core": "workspace:^",
+		"zod": "^4.2.0"
+	},
+	"devDependencies": {
+		"@alxia/client": "workspace:^",
+		"@types/bun": "^1.4.2",
+		"typescript": "^6.0.3"
+	}
+}

package/templates/api/src/app.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from 'bun:test';
+import { client } from '@alxia/client';
+import { apiKey, app } from './app';
+
+const json = { 'content-type': 'application/json', 'x-api-key': apiKey };
+
+test('creates a todo from JSON', async () => {
+	const response = await app.request('/todos', {
+		method: 'POST',
+		headers: json,
+		body: JSON.stringify({ title: 'Write a route' }),
+	});
+	expect(response.status).toBe(201);
+	expect(await response.json()).toEqual({
+		id: expect.any(Number),
+		title: 'Write a route',
+		done: false,
+	});
+});
+
+test('refuses an empty title with a 400 naming it', async () => {
+	const response = await app.request('/todos', {
+		method: 'POST',
+		headers: json,
+		body: JSON.stringify({ title: '' }),
+	});
+	expect(response.status).toBe(400);
+	expect((await response.json()).issues[0].path).toEqual(['title']);
+});
+
+test('the typed client reads each status the route answers', async () => {
+	// Given the app itself, the client calls its fetch in process.
+	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
+
+	const anonymous = await client(app).post('/todos', {
+		body: { title: 'No key' },
+	});
+	expect(anonymous.status).toBe(401);
+	if (anonymous.status === 401)
+		expect(anonymous.data.error).toBe('unauthorized');
+});

package/templates/api/src/app.ts

@@ -0,0 +1,33 @@
+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';
+
+// A hook of the routes it is given to: it answers 401 without the key, and
+// that 401 joins the type of each, so the client reads it.
+const requireKey = defineHook(({ request, reply }) =>
+	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);
+		},
+	);
+
+export type App = typeof app;

package/templates/api/src/server.ts

@@ -0,0 +1,4 @@
+import { app } from './app';
+
+const server = app.listen(Number(Bun.env['PORT'] ?? 3000));
+console.log(`listening on ${server.url}`);

package/templates/api/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"compilerOptions": {
+		"types": ["bun"],
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"moduleResolution": "bundler",
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true,
+		"strict": true,
+		"noImplicitOverride": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"forceConsistentCasingInFileNames": true
+	},
+	"include": ["src"]
+}

package/templates/react-router/.dockerignore

@@ -0,0 +1,4 @@
+.react-router
+build
+node_modules
+README.md

package/templates/react-router/Dockerfile

@@ -0,0 +1,29 @@
+# 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
+
+# Every dependency, then react-router build: build/client and
+# build/server/index.js.
+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
+
+# 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
+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"]

package/templates/react-router/README.md

@@ -0,0 +1,87 @@
+# Welcome to React Router!
+
+A modern, production-ready template for building full-stack React applications using React Router.
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/remix-run/react-router-templates/tree/main/default)
+
+## Features
+
+- 🚀 Server-side rendering
+- ⚡️ Hot Module Replacement (HMR)
+- 📦 Asset bundling and optimization
+- 🔄 Data loading and mutations
+- 🔒 TypeScript by default
+- 🎉 TailwindCSS for styling
+- 📖 [React Router docs](https://reactrouter.com/)
+
+## Getting Started
+
+### Installation
+
+Install the dependencies:
+
+```bash
+bun install
+```
+
+### Development
+
+Start the development server with HMR:
+
+```bash
+bun dev
+```
+
+Your application will be available at `http://localhost:5173`.
+
+## Building for Production
+
+Create a production build:
+
+```bash
+bun run build
+```
+
+## Deployment
+
+### Docker Deployment
+
+To build and run using Docker:
+
+```bash
+docker build -t my-app .
+
+# Run the container
+docker run -p 3000:3000 my-app
+```
+
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### DIY Deployment
+
+The build is production-ready: `bun run start` runs `build/server/index.js` on Bun.
+
+Make sure to deploy the output of `bun run build`
+
+```
+├── package.json
+├── bun.lock
+├── build/
+│   ├── client/    # Static assets
+│   └── server/    # Server-side code
+```
+
+## Styling
+
+This template comes with [Tailwind CSS](https://tailwindcss.com/) already configured for a simple default starting experience. You can use whatever CSS framework you prefer.
+
+---
+
+Built with ❤️ using React Router.

package/templates/react-router/_bunfig.toml

@@ -0,0 +1,4 @@
+[run]
+# The React Router CLI is a node script: this starts it on Bun, which
+# alxia's server needs, even where a node is installed.
+bun = true

package/templates/react-router/app/app.css

@@ -0,0 +1,15 @@
+@import "tailwindcss";
+
+@theme {
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif,
+    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+html,
+body {
+  @apply bg-white dark:bg-gray-950;
+
+  @media (prefers-color-scheme: dark) {
+    color-scheme: dark;
+  }
+}