@alxia/create 0.1.7 → 0.3.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 +80 -25
- package/dist/args.d.ts +3 -1
- package/dist/args.d.ts.map +1 -1
- package/dist/index.js +19 -9
- package/dist/index.js.map +7 -7
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/registry.d.ts +2 -0
- package/dist/registry.d.ts.map +1 -1
- package/dist/versions.d.ts +5 -2
- package/dist/versions.d.ts.map +1 -1
- package/docs/README.md +16 -6
- package/docs/guide.md +428 -47
- package/docs/roadmap.md +24 -0
- package/docs/troubleshooting.md +152 -9
- package/package.json +16 -5
- package/templates/api/.env.example +9 -1
- package/templates/api/README.md +40 -12
- package/templates/api/openapi.yaml +13 -9
- package/templates/api/package.json +5 -3
- package/templates/api/src/app.spec.ts +42 -28
- package/templates/api/src/app.ts +13 -3
- package/templates/api/src/context.ts +3 -4
- package/templates/api/src/env.ts +20 -0
- package/templates/api/src/generated/alxia.ts +3 -3
- package/templates/api/src/generated/operations.ts +3 -3
- package/templates/api/src/generated/paths.ts +6 -6
- package/templates/api/src/generated/types.ts +14 -10
- package/templates/api/src/generated/zod.ts +6 -2
- package/templates/api/src/routes/todos.ts +2 -2
- package/templates/api/src/server.ts +8 -16
- package/templates/graphql/.dockerignore +6 -0
- package/templates/graphql/.env.example +3 -0
- package/templates/graphql/.vscode/extensions.json +3 -0
- package/templates/graphql/.vscode/settings.json +8 -0
- package/templates/graphql/Dockerfile +26 -0
- package/templates/graphql/README.md +185 -0
- package/templates/graphql/_biome.json +32 -0
- package/templates/graphql/codegen.ts +22 -0
- package/templates/graphql/gitignore +6 -0
- package/templates/graphql/package.json +35 -0
- package/templates/graphql/schema.graphql +26 -0
- package/templates/graphql/src/app.spec.ts +146 -0
- package/templates/graphql/src/app.ts +18 -0
- package/templates/graphql/src/context.ts +26 -0
- package/templates/graphql/src/env.ts +8 -0
- package/templates/graphql/src/generated/resolvers.ts +180 -0
- package/templates/graphql/src/graphql.d.ts +6 -0
- package/templates/graphql/src/loaders.ts +13 -0
- package/templates/graphql/src/resolvers.ts +39 -0
- package/templates/graphql/src/schema.ts +6 -0
- package/templates/graphql/src/server.ts +10 -0
- package/templates/graphql/src/store.ts +38 -0
- package/templates/graphql/tsconfig.json +25 -0
- package/templates/minimal/.dockerignore +6 -0
- package/templates/minimal/.vscode/extensions.json +3 -0
- package/templates/minimal/.vscode/settings.json +8 -0
- package/templates/minimal/Dockerfile +26 -0
- package/templates/minimal/README.md +107 -0
- package/templates/minimal/_biome.json +32 -0
- package/templates/minimal/gitignore +6 -0
- package/templates/minimal/package.json +25 -0
- package/templates/minimal/src/index.spec.ts +12 -0
- package/templates/minimal/src/index.ts +17 -0
- package/templates/minimal/tsconfig.json +25 -0
- package/templates/react-router/package.json +2 -2
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# A minimal alxia app
|
|
2
|
+
|
|
3
|
+
An [alxia](https://github.com/softistx/alxia) app in one route, made with
|
|
4
|
+
`bun create @alxia`: the quickest way to see alxia run. Nothing else is set
|
|
5
|
+
up: no OpenAPI, no code generation, no validator.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
// src/index.ts
|
|
9
|
+
export const app = alxia().get("/", ({ reply }) =>
|
|
10
|
+
reply(200, { hello: "world" }),
|
|
11
|
+
);
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
bun dev # NODE_ENV=development: http://localhost:3000, reloaded on every change
|
|
16
|
+
curl localhost:3000 # {"hello":"world"}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`bun dev` sets `NODE_ENV=development`, alxia's dev switch: `listen`
|
|
20
|
+
prints the route table, a 404 hints at the closest route and a 500 shows
|
|
21
|
+
its error. Under any other `NODE_ENV`, none of them is.
|
|
22
|
+
|
|
23
|
+
- `src/index.ts`: the app, and `app.listen()` on `PORT` (3000 by default)
|
|
24
|
+
when the file is run, not when a test imports it. `listen` shuts the app
|
|
25
|
+
down gracefully on `SIGINT` and `SIGTERM`.
|
|
26
|
+
- `src/index.spec.ts`: `app.request()`, no port: the request goes through
|
|
27
|
+
the app and the response comes back.
|
|
28
|
+
- `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
|
|
29
|
+
|
|
30
|
+
## Where next
|
|
31
|
+
|
|
32
|
+
- Add a route: `.get("/users/:id", ({ params, reply }) => …)` after the
|
|
33
|
+
first. Order is meaning: a middleware given to `use` applies to the routes
|
|
34
|
+
after it.
|
|
35
|
+
- Validate a body with `validate` and Zod (`bun add zod`), see
|
|
36
|
+
[Routes and validation](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/routes.md).
|
|
37
|
+
- Describe the API first, with an OpenAPI document and the operations
|
|
38
|
+
generated from it: `bun create @alxia my-service --template api`.
|
|
39
|
+
- Serve GraphQL: `bun create @alxia my-service --template graphql`.
|
|
40
|
+
|
|
41
|
+
## Test
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
bun test # src/index.spec.ts: in process, no port
|
|
45
|
+
bun run typecheck
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Lint and format
|
|
49
|
+
|
|
50
|
+
[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
|
|
51
|
+
sets it: Biome's recommended rules, spaces, double quotes, imports
|
|
52
|
+
sorted. What the build writes, `dist/`, is skipped.
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
bun run check # lint, format and sort imports, fixing what it can
|
|
56
|
+
bun run lint # lint only
|
|
57
|
+
bun run format # format only, in place
|
|
58
|
+
bun run check:ci # what CI runs: changes nothing, fails on an error
|
|
59
|
+
bun run verify # check:ci, typecheck, then test
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`bun run check:ci`, not `bun ci`: `bun ci` is Bun's frozen-lockfile
|
|
63
|
+
install. In VS Code, `.vscode/` recommends Biome's extension and formats
|
|
64
|
+
on save with it.
|
|
65
|
+
|
|
66
|
+
`@biomejs/biome` is pinned exactly, since a release of Biome may format
|
|
67
|
+
differently. To move it:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
bun add --dev --exact @biomejs/biome@latest
|
|
71
|
+
bunx biome migrate --write
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Build
|
|
75
|
+
|
|
76
|
+
`bun run build` bundles the server and its dependencies into one file,
|
|
77
|
+
`dist/index.js`, minified, with its source map beside it, and `bun start`
|
|
78
|
+
runs it: what production and the image run.
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
bun run build # dist/index.js and dist/index.js.map
|
|
82
|
+
bun start # NODE_ENV=production bun dist/index.js
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`bun start` before any build fails with `Module not found
|
|
86
|
+
"dist/index.js"`: build first. `dist/` needs Bun and nothing else, no
|
|
87
|
+
`node_modules`. A dependency that cannot be bundled, a native addon, is
|
|
88
|
+
left out with `--external <name>` in the `build` script, and must then be
|
|
89
|
+
installed beside `dist/`.
|
|
90
|
+
|
|
91
|
+
## Docker
|
|
92
|
+
|
|
93
|
+
The `Dockerfile` builds in a stage of its own, on `oven/bun:1`, and runs
|
|
94
|
+
on `oven/bun:1-alpine`. The build stage installs every dependency with
|
|
95
|
+
`--frozen-lockfile`, from the `bun.lock` that `bun install` wrote (commit
|
|
96
|
+
it), and runs `bun run build`. The image holds `dist/` alone, no
|
|
97
|
+
`node_modules` and no `src/`, and runs `bun --no-install dist/index.js` as
|
|
98
|
+
its non-root `bun` user. `listen` drains the app and exits on `SIGTERM`,
|
|
99
|
+
so `docker stop` is immediate.
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
docker build -t my-app .
|
|
103
|
+
docker run --rm -p 3000:3000 my-app
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Next: [Getting started](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/getting-started.md)
|
|
107
|
+
and the rest of [`@alxia/core`'s guide](https://github.com/softistx/alxia/tree/develop/packages/core/docs).
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
|
|
3
|
+
"vcs": {
|
|
4
|
+
"enabled": true,
|
|
5
|
+
"clientKind": "git",
|
|
6
|
+
"useIgnoreFile": true
|
|
7
|
+
},
|
|
8
|
+
"files": {
|
|
9
|
+
"includes": ["**", "!!**/dist"]
|
|
10
|
+
},
|
|
11
|
+
"formatter": {
|
|
12
|
+
"enabled": true,
|
|
13
|
+
"indentStyle": "space"
|
|
14
|
+
},
|
|
15
|
+
"linter": {
|
|
16
|
+
"enabled": true,
|
|
17
|
+
"rules": {
|
|
18
|
+
"preset": "recommended",
|
|
19
|
+
"complexity": {
|
|
20
|
+
"useLiteralKeys": "off"
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"assist": {
|
|
25
|
+
"enabled": true,
|
|
26
|
+
"actions": {
|
|
27
|
+
"source": {
|
|
28
|
+
"organizeImports": "on"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "my-app",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"scripts": {
|
|
6
|
+
"dev": "NODE_ENV=development bun --hot src/index.ts",
|
|
7
|
+
"build": "bun build src/index.ts --target=bun --outdir=dist --minify --sourcemap=linked",
|
|
8
|
+
"start": "NODE_ENV=production bun dist/index.js",
|
|
9
|
+
"test": "bun test",
|
|
10
|
+
"typecheck": "tsc --noEmit",
|
|
11
|
+
"lint": "biome lint",
|
|
12
|
+
"format": "biome format --write",
|
|
13
|
+
"check": "biome check --write",
|
|
14
|
+
"check:ci": "biome ci",
|
|
15
|
+
"verify": "bun run check:ci && bun run typecheck && bun run test"
|
|
16
|
+
},
|
|
17
|
+
"dependencies": {
|
|
18
|
+
"@alxia/core": "workspace:^"
|
|
19
|
+
},
|
|
20
|
+
"devDependencies": {
|
|
21
|
+
"@biomejs/biome": "2.5.15",
|
|
22
|
+
"@types/bun": "^1.4.2",
|
|
23
|
+
"typescript": "^6.0.3"
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { expect, test } from "bun:test";
|
|
2
|
+
import { app } from "./index";
|
|
3
|
+
|
|
4
|
+
test("GET / says hello", async () => {
|
|
5
|
+
const response = await app.request("/");
|
|
6
|
+
expect(response.status).toBe(200);
|
|
7
|
+
expect(await response.json()).toEqual({ hello: "world" });
|
|
8
|
+
});
|
|
9
|
+
|
|
10
|
+
test("a path no route has is a 404", async () => {
|
|
11
|
+
expect((await app.request("/nowhere")).status).toBe(404);
|
|
12
|
+
});
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { alxia } from "@alxia/core";
|
|
2
|
+
|
|
3
|
+
export const app = alxia().get("/", ({ reply }) =>
|
|
4
|
+
reply(200, { hello: "world" }),
|
|
5
|
+
);
|
|
6
|
+
|
|
7
|
+
// Only when this file is the entry: the test imports `app` and listens on
|
|
8
|
+
// no port.
|
|
9
|
+
if (import.meta.main) {
|
|
10
|
+
// In dev, the URL and the route table; in production, the URL alone. On
|
|
11
|
+
// SIGINT and SIGTERM, listen drains the requests in flight and exits.
|
|
12
|
+
app.listen({
|
|
13
|
+
port: Number(Bun.env["PORT"] ?? 3000),
|
|
14
|
+
onListen: ({ dev, table, url }) =>
|
|
15
|
+
console.log(dev ? table : `listening on ${url}`),
|
|
16
|
+
});
|
|
17
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"types": ["bun"],
|
|
4
|
+
"lib": ["ESNext", "DOM"],
|
|
5
|
+
"target": "ESNext",
|
|
6
|
+
"module": "ESNext",
|
|
7
|
+
"moduleDetection": "force",
|
|
8
|
+
"moduleResolution": "bundler",
|
|
9
|
+
"verbatimModuleSyntax": true,
|
|
10
|
+
"noEmit": true,
|
|
11
|
+
"skipLibCheck": true,
|
|
12
|
+
"resolveJsonModule": true,
|
|
13
|
+
"strict": true,
|
|
14
|
+
"noImplicitOverride": true,
|
|
15
|
+
"noImplicitReturns": true,
|
|
16
|
+
"noFallthroughCasesInSwitch": true,
|
|
17
|
+
"noUncheckedIndexedAccess": true,
|
|
18
|
+
"exactOptionalPropertyTypes": true,
|
|
19
|
+
"noPropertyAccessFromIndexSignature": true,
|
|
20
|
+
"noUnusedLocals": true,
|
|
21
|
+
"noUnusedParameters": true,
|
|
22
|
+
"forceConsistentCasingInFileNames": true
|
|
23
|
+
},
|
|
24
|
+
"include": ["src"]
|
|
25
|
+
}
|
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
6
|
"build": "react-router build",
|
|
7
|
-
"dev": "react-router dev",
|
|
8
|
-
"start": "bun build/server/index.js",
|
|
7
|
+
"dev": "NODE_ENV=development react-router dev",
|
|
8
|
+
"start": "NODE_ENV=production bun build/server/index.js",
|
|
9
9
|
"typecheck": "react-router typegen && tsc",
|
|
10
10
|
"lint": "biome lint",
|
|
11
11
|
"format": "biome format --write",
|