@alxia/create 0.5.13 → 0.6.0

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
@@ -36,8 +36,8 @@ bun create @alxia my-site --template react-router
36
36
  | template | what it writes |
37
37
  | --- | --- |
38
38
  | `minimal` | the smallest alxia app: `src/index.ts` exports `app = alxia().get("/", …)` and listens on `PORT` only when it is the entry file, `src/index.spec.ts` calls it with `app.request()`; `bun dev` (`NODE_ENV=development bun --hot`), `build`, `start`, `typecheck`, a strict `tsconfig.json`, Biome and `verify` (`check:ci`, `typecheck`, then `test`), a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.vscode/` and a README. One dependency, `@alxia/core`: no OpenAPI, no code generation, no validator, no env file |
39
- | `api` | an `@alxia/core` app with Zod, OpenAPI spec first: `openapi.yaml` declares `GET /todos`, `POST /todos` and `GET /todos/{id}`; `bun run generate` writes `src/generated/` from it with [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen) (`openapi-codegen.config.ts`), committed, so nothing is generated at install or build; `src/env.ts` reads `PORT`, `API_KEY`, `API_DOCS` and an optional `TRUSTED_PROXIES` (CIDR ranges, which adds `trustProxy({ trusted, untrusted: "refuse" })` to the base when set: `ctx.ip` from a trusted proxy's `X-Forwarded-For`, a forwarding header from any other connection refused, health probes untouched) with `defineEnv` from [`@alxia/env`](https://www.npmjs.com/package/@alxia/env), `API_KEY` a secret defaulting to `dev-key` under `NODE_ENV` `development` and `test` alone, required anywhere else; `src/context.ts` holds the base the routes read, `alxia({ errors: "problem" })` so alxia's own errors are RFC 9457 problems as `openapi.yaml` declares them, and registers it with `@alxia/core`'s `Register`; `src/routes/todos.ts`, made with `defineRoutes()`, reads that context with no import of the app and binds each operation with `route(operation, …middlewares, handler)`, as `route(operations.createTodo, requireKey, handler)`, where `requireKey`, made with `defineMiddleware`, answers 401 without an API key, and the operation's schemas validate the request and check the handler's reply; `src/app.ts` mounts `health()` (`GET /health`, `GET /ready`), `apiDocs` from `@alxia/openapi` (the API reference at `/docs`, from `openapi.yaml` imported into the bundle; on in development, else with `API_DOCS=true`) and the routes on the base; a `bun test` spec, `src/proxy.spec.ts`, building the base behind `TRUSTED_PROXIES` and calling `app.fetch` with a peer, `src/env.spec.ts`, checking that a malformed `TRUSTED_PROXIES` stops the app, and a `bun test` spec calling the app through the typed [`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz) client over the generated `operations.ts`, its `fetch` being `app.fetch` (in process, no server; replies narrowed on their status), keeping one `app.request()` test, and asserting `matchesSpec` from [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every operation has its route, and `strict: true` also fails on a route outside the spec; `bun dev` (`NODE_ENV=development`) restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, Biome (`biome.json`, `lint`, `format`, `check`, `check:ci`), `verify`, starting with `generate --check`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example`, `.vscode/` and a README. `@alxia/openapi` is a dependency; `@nxgt/httpyz`, `@nxgt/openapi-httpyz` and `@nxgt/openapi-codegen` are devDependencies |
40
- | `graphql` | a GraphQL API with [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) through [`@alxia/graphql`](https://www.npmjs.com/package/@alxia/graphql), schema first: `schema.graphql` is the contract (`Query`, `Mutation`, `Subscription`); `bun run generate` writes `src/generated/resolvers.ts` from it with [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) (`codegen.ts`), committed, typing `Resolvers` with the app's context; `src/context.ts` holds the base and `viewerOf`, a middleware reading `Authorization: Bearer <token>` so every resolver reads a typed `viewer`; `src/loaders.ts`, `createLoaders()`, the [DataLoader](https://github.com/graphql/dataloader)s of one request, built per request by the `context` option of `graphql()` in `src/app.ts` so `Note.author` loads the authors of a list of notes in one batch (`findUsers`) instead of one call per note; `src/resolvers.ts`; `src/schema.ts` and `src/app.ts` mounting `health()` and `graphql(app, { schema, context })`, GraphiQL on in dev alone; `src/env.ts` (`PORT` and the optional `TRUSTED_PROXIES`, as `api`) with `defineEnv`; `src/store.ts`, in memory, with the pub/sub of the `noteAdded` subscription (server-sent events); a `bun test` spec posting to `/graphql` through `app.request()`, `src/proxy.spec.ts`, the base behind `TRUSTED_PROXIES`, and `src/env.spec.ts`, a malformed one refused; the same scripts, `Dockerfile`, Biome and `.vscode/` as `api`, `verify` starting with `generate --check`, and a `.env.example`. `@alxia/graphql`, `@alxia/env`, `dataloader`, `graphql` and `graphql-yoga` are dependencies; the code generator is a devDependency |
39
+ | `api` | an `@alxia/core` app with Zod, OpenAPI spec first: `openapi.yaml` declares `GET /todos`, `POST /todos` and `GET /todos/{id}`; `bun run generate` writes `src/generated/` from it with [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen) (`openapi-codegen.config.ts`), committed, so nothing is generated at install or build; `src/env.ts` reads `PORT`, `API_KEY`, `API_DOCS` and an optional `TRUSTED_PROXIES` (CIDR ranges, which adds `trustProxy({ trusted, untrusted: "refuse" })` to the base when set: `ctx.ip` from a trusted proxy's `X-Forwarded-For`, a forwarding header from any other connection refused, health probes untouched) with `defineEnv` from [`@alxia/env`](https://www.npmjs.com/package/@alxia/env), `API_KEY` a secret defaulting to `dev-key` under `NODE_ENV` `development` and `test` alone, required anywhere else; `src/context.ts` holds the base the routes read, `alxia({ errors: "problem" })` so alxia's own errors are RFC 9457 problems as `openapi.yaml` declares them, and registers it with `@alxia/core`'s `Register`; `src/routes/todos.ts`, made with `defineRoutes()`, reads that context with no import of the app and binds each operation with `route(operation, …middlewares, handler)`, as `route(operations.createTodo, requireKey, handler)`, where `requireKey`, made with `defineMiddleware`, answers 401 without an API key, and the operation's schemas validate the request and check the handler's reply; `src/app.ts` mounts `health()` (`GET /health`, `GET /ready`), `apiDocs` from `@alxia/openapi` (the API reference at `/docs`, from `openapi.yaml` imported into the bundle; on in development, else with `API_DOCS=true`) and the routes on the base; a `bun test` spec, `src/proxy.spec.ts`, building the base behind `TRUSTED_PROXIES` and calling `app.fetch` with a peer, `src/env.spec.ts`, checking that a malformed `TRUSTED_PROXIES` stops the app (the keyword `cloudflare` expands to Cloudflare's ranges), and a `bun test` spec calling the app through the typed [`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz) client over the generated `operations.ts`, its `fetch` being `app.fetch` (in process, no server; replies narrowed on their status), keeping one `app.request()` test, and asserting `matchesSpec` from [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every operation has its route, and `strict: true` also fails on a route outside the spec; `bun dev` (`NODE_ENV=development`) restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, Biome (`biome.json`, `lint`, `format`, `check`, `check:ci`), `verify`, starting with `generate --check`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example`, `.vscode/` and a README. `@alxia/openapi` is a dependency; `@nxgt/httpyz`, `@nxgt/openapi-httpyz` and `@nxgt/openapi-codegen` are devDependencies |
40
+ | `graphql` | a GraphQL API with [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) through [`@alxia/graphql`](https://www.npmjs.com/package/@alxia/graphql), schema first: `schema.graphql` is the contract (`Query`, `Mutation`, `Subscription`); `bun run generate` writes `src/generated/resolvers.ts` from it with [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) (`codegen.ts`), committed, typing `Resolvers` with the app's context; `src/context.ts` holds the base and `viewerOf`, a middleware reading `Authorization: Bearer <token>` so every resolver reads a typed `viewer`; `src/loaders.ts`, `createLoaders()`, the [DataLoader](https://github.com/graphql/dataloader)s of one request, built per request by the `context` option of `graphql()` in `src/app.ts` so `Note.author` loads the authors of a list of notes in one batch (`findUsers`) instead of one call per note; `src/resolvers.ts`; `src/schema.ts` and `src/app.ts` mounting `health()` and `graphql(app, { schema, context })`, GraphiQL on in dev alone; `src/env.ts` (`PORT` and the optional `TRUSTED_PROXIES`, as `api`) with `defineEnv`; `src/store.ts`, in memory, with the pub/sub of the `noteAdded` subscription (server-sent events); a `bun test` spec posting to `/graphql` through `app.request()`, `src/proxy.spec.ts`, the base behind `TRUSTED_PROXIES`, and `src/env.spec.ts`, a malformed one refused (the keyword `cloudflare` is accepted); the same scripts, `Dockerfile`, Biome and `.vscode/` as `api`, `verify` starting with `generate --check`, and a `.env.example`. `@alxia/graphql`, `@alxia/env`, `dataloader`, `graphql` and `graphql-yoga` are dependencies; the code generator is a devDependency |
41
41
  | `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, `dev` under `NODE_ENV=development`, `start` running `NODE_ENV=production bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, a `Dockerfile` running on `oven/bun:1-alpine` in place of React Router's Node one, and Biome as the `api` project has it, the scaffold formatted by it once. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
42
42
 
43
43
  The heart of the `api` project, its middleware and a route bound to an
package/docs/guide.md CHANGED
@@ -335,7 +335,7 @@ instead:
335
335
  ### `src/env.ts`
336
336
 
337
337
  ```ts
338
- import { trustProxy } from "@alxia/core";
338
+ import { cloudflareRanges, trustProxy } from "@alxia/core";
339
339
  import { defineEnv } from "@alxia/env";
340
340
  import { z } from "zod";
341
341
 
@@ -364,7 +364,10 @@ export const env = defineEnv(
364
364
  list
365
365
  .split(",")
366
366
  .map((range) => range.trim())
367
- .filter(Boolean),
367
+ .filter(Boolean)
368
+ .flatMap((range) =>
369
+ range === "cloudflare" ? cloudflareRanges : [range],
370
+ ),
368
371
  )
369
372
  .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
370
373
  .transform((ranges) => (ranges.length > 0 ? ranges : undefined))
@@ -1078,6 +1081,15 @@ the base only when it is set:
1078
1081
  TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12 bun start
1079
1082
  ```
1080
1083
 
1084
+ Behind Cloudflare and a reverse proxy, the keyword `cloudflare` stands for
1085
+ Cloudflare's published ranges (`cloudflareRanges` of `@alxia/core`), beside
1086
+ your own proxy's network
1087
+ ([why every hop is listed](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#behind-cloudflare-and-a-reverse-proxy)):
1088
+
1089
+ ```sh
1090
+ TRUSTED_PROXIES=cloudflare,172.16.0.0/12 bun start
1091
+ ```
1092
+
1081
1093
  - **From a trusted proxy**, `X-Forwarded-For` sets `ctx.ip`, read from the
1082
1094
  right, and `X-Forwarded-Proto` and `X-Forwarded-Host` give
1083
1095
  `originalUrl(ctx)`.
package/docs/roadmap.md CHANGED
@@ -7,7 +7,8 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
- Nothing in progress.
10
+ - **`TRUSTED_PROXIES=cloudflare`.** The `api` and `graphql` templates expand
11
+ the keyword `cloudflare` to Cloudflare's ranges, beside CIDR entries.
11
12
 
12
13
  ## Next
13
14
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.5.13",
3
+ "version": "0.6.0",
4
4
  "description": "Start an alxia app: `bun create @alxia` writes a minimal API, a spec-first one, a GraphQL one, or React Router's official template served by alxia",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -41,11 +41,11 @@
41
41
  ]
42
42
  },
43
43
  "devDependencies": {
44
- "@alxia/core": "^0.17.1",
45
- "@alxia/env": "^0.3.1",
46
- "@alxia/graphql": "^0.13.0",
47
- "@alxia/openapi": "^0.6.12",
48
- "@alxia/react-router": "^0.34.0",
44
+ "@alxia/core": "^0.20.0",
45
+ "@alxia/env": "^0.5.0",
46
+ "@alxia/graphql": "^0.15.0",
47
+ "@alxia/openapi": "^0.6.15",
48
+ "@alxia/react-router": "^0.58.0",
49
49
  "@graphql-codegen/cli": "7.4.3",
50
50
  "@graphql-codegen/typescript": "6.1.0",
51
51
  "@graphql-codegen/typescript-resolvers": "6.1.0",
@@ -13,4 +13,6 @@ PORT=3000
13
13
  # comma-separated CIDR ranges or addresses, optional, unset by default: the proxies in front of
14
14
  # the app, a load balancer's. Set, X-Forwarded-For from one of them sets ctx.ip, and a forwarding
15
15
  # header from any other connection is refused with a 403. Unset, no forwarding header is read.
16
+ # Behind Cloudflare, the keyword `cloudflare` stands for its published ranges:
17
+ # TRUSTED_PROXIES=cloudflare,172.16.0.0/12
16
18
  # TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
@@ -9,6 +9,8 @@ const todos: Todo[] = [];
9
9
  // alxia's own errors — a 400 the schemas refuse, a 404 no route matches, a
10
10
  // 500 — are RFC 9457 problems, as openapi.yaml declares them.
11
11
  //
12
+ // Behind Cloudflare: TRUSTED_PROXIES=cloudflare,172.16.0.0/12 (`cloudflare` is
13
+ // its published ranges, then your own proxy's).
12
14
  // Behind a load balancer, set TRUSTED_PROXIES to its range: its
13
15
  // X-Forwarded-For then sets ctx.ip, and a forwarding header from any other
14
16
  // connection is refused with a 403. A request that carries none, a health
@@ -28,3 +28,15 @@ test("comma-separated ranges are trimmed, and an empty list declares no proxy",
28
28
  expect(env.TRUSTED_PROXIES).toEqual(["10.0.0.0/8", "172.16.0.0/12"]);
29
29
  expect((await load("")).env.TRUSTED_PROXIES).toBeUndefined();
30
30
  });
31
+
32
+ test("the keyword cloudflare expands to Cloudflare's ranges, beside other entries", async () => {
33
+ const { cloudflareRanges } = await import("@alxia/core");
34
+ const { env } = await load("cloudflare, 172.16.0.0/12");
35
+ expect(env.TRUSTED_PROXIES).toEqual([...cloudflareRanges, "172.16.0.0/12"]);
36
+ });
37
+
38
+ test("the keyword is lowercase: Cloudflare stops the app, naming the variable", async () => {
39
+ await expect(load("Cloudflare")).rejects.toThrow(
40
+ "TRUSTED_PROXIES.0: not a CIDR range or address",
41
+ );
42
+ });
@@ -1,4 +1,4 @@
1
- import { trustProxy } from "@alxia/core";
1
+ import { cloudflareRanges, trustProxy } from "@alxia/core";
2
2
  import { defineEnv } from "@alxia/env";
3
3
  import { z } from "zod";
4
4
 
@@ -21,8 +21,8 @@ const isRange = (range: string) => {
21
21
  // print as `***`. API_KEY defaults to `dev-key` in development and test
22
22
  // alone: deployed, it is required. API_DOCS serves the API reference at
23
23
  // /docs: on in development, off unless set elsewhere. TRUSTED_PROXIES is
24
- // unset by default: the app then reads no forwarding header. Set it behind a
25
- // load balancer (src/context.ts).
24
+ // unset by default: the app then reads no forwarding header. Set it
25
+ // behind a load balancer (src/context.ts).
26
26
  export const env = defineEnv(
27
27
  {
28
28
  PORT: z.coerce.number().default(3000),
@@ -34,7 +34,10 @@ export const env = defineEnv(
34
34
  list
35
35
  .split(",")
36
36
  .map((range) => range.trim())
37
- .filter(Boolean),
37
+ .filter(Boolean)
38
+ .flatMap((range) =>
39
+ range === "cloudflare" ? cloudflareRanges : [range],
40
+ ),
38
41
  )
39
42
  .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
40
43
  .transform((ranges) => (ranges.length > 0 ? ranges : undefined))
@@ -5,4 +5,6 @@ PORT=3000
5
5
  # comma-separated CIDR ranges or addresses, optional, unset by default: the proxies in front of
6
6
  # the app, a load balancer's. Set, X-Forwarded-For from one of them sets ctx.ip, and a forwarding
7
7
  # header from any other connection is refused with a 403. Unset, no forwarding header is read.
8
+ # Behind Cloudflare, the keyword `cloudflare` stands for its published ranges:
9
+ # TRUSTED_PROXIES=cloudflare,172.16.0.0/12
8
10
  # TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
@@ -19,6 +19,8 @@ const viewerOf = defineMiddleware(({ request }, next) => {
19
19
 
20
20
  // The base: what every resolver reads, decorated or derived here.
21
21
  //
22
+ // Behind Cloudflare: TRUSTED_PROXIES=cloudflare,172.16.0.0/12 (`cloudflare` is
23
+ // its published ranges, then your own proxy's).
22
24
  // Behind a load balancer, set TRUSTED_PROXIES to its range: its
23
25
  // X-Forwarded-For then sets ctx.ip, and a forwarding header from any other
24
26
  // connection is refused with a 403. A request that carries none, a health
@@ -28,3 +28,15 @@ test("comma-separated ranges are trimmed, and an empty list declares no proxy",
28
28
  expect(env.TRUSTED_PROXIES).toEqual(["10.0.0.0/8", "172.16.0.0/12"]);
29
29
  expect((await load("")).env.TRUSTED_PROXIES).toBeUndefined();
30
30
  });
31
+
32
+ test("the keyword cloudflare expands to Cloudflare's ranges, beside other entries", async () => {
33
+ const { cloudflareRanges } = await import("@alxia/core");
34
+ const { env } = await load("cloudflare, 172.16.0.0/12");
35
+ expect(env.TRUSTED_PROXIES).toEqual([...cloudflareRanges, "172.16.0.0/12"]);
36
+ });
37
+
38
+ test("the keyword is lowercase: Cloudflare stops the app, naming the variable", async () => {
39
+ await expect(load("Cloudflare")).rejects.toThrow(
40
+ "TRUSTED_PROXIES.0: not a CIDR range or address",
41
+ );
42
+ });
@@ -1,4 +1,4 @@
1
- import { trustProxy } from "@alxia/core";
1
+ import { cloudflareRanges, trustProxy } from "@alxia/core";
2
2
  import { defineEnv } from "@alxia/env";
3
3
  import { z } from "zod";
4
4
 
@@ -14,8 +14,8 @@ const isRange = (range: string) => {
14
14
 
15
15
  // Checked once, when this module is first imported: a malformed variable
16
16
  // stops the process, with every issue, before it listens. TRUSTED_PROXIES is
17
- // unset by default: the app then reads no forwarding header. Set it behind a
18
- // load balancer (src/context.ts).
17
+ // unset by default: the app then reads no forwarding header. Set it
18
+ // behind a load balancer (src/context.ts).
19
19
  export const env = defineEnv({
20
20
  PORT: z.coerce.number().default(3000),
21
21
  TRUSTED_PROXIES: z
@@ -24,7 +24,10 @@ export const env = defineEnv({
24
24
  list
25
25
  .split(",")
26
26
  .map((range) => range.trim())
27
- .filter(Boolean),
27
+ .filter(Boolean)
28
+ .flatMap((range) =>
29
+ range === "cloudflare" ? cloudflareRanges : [range],
30
+ ),
28
31
  )
29
32
  .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
30
33
  .transform((ranges) => (ranges.length > 0 ? ranges : undefined))