@bractjs/bractjs 0.1.27 → 0.1.29
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/bin/cli.ts +18 -1
- package/package.json +3 -2
- package/src/__tests__/codegen-write.test.ts +67 -0
- package/src/__tests__/codegen.test.ts +29 -2
- package/src/__tests__/compile-safety.test.ts +4 -0
- package/src/__tests__/csp.test.ts +10 -0
- package/src/__tests__/define-actions.test.ts +69 -0
- package/src/__tests__/env.test.ts +18 -0
- package/src/__tests__/fetcher-store.test.ts +67 -0
- package/src/__tests__/fixtures/app/root.tsx +7 -2
- package/src/__tests__/fixtures/app/routes/boom.tsx +9 -0
- package/src/__tests__/fixtures/app/routes/client-only.tsx +16 -0
- package/src/__tests__/fixtures/app/routes/counter.tsx +16 -0
- package/src/__tests__/fixtures/app/routes/data-only.tsx +16 -0
- package/src/__tests__/fixtures/app/routes/features-demo.tsx +28 -0
- package/src/__tests__/fixtures/app/routes/intent-demo.tsx +46 -0
- package/src/__tests__/fixtures/app/routes/protected-client-only.tsx +15 -0
- package/src/__tests__/fixtures/app/routes/search-demo.tsx +39 -0
- package/src/__tests__/form-data-helpers.test.ts +43 -0
- package/src/__tests__/headers.test.ts +111 -0
- package/src/__tests__/integration.test.ts +90 -0
- package/src/__tests__/layout-registry.test.ts +7 -3
- package/src/__tests__/loader.test.ts +32 -1
- package/src/__tests__/matcher.test.ts +29 -0
- package/src/__tests__/module-registry.test.ts +2 -3
- package/src/__tests__/nav-utils.test.ts +46 -0
- package/src/__tests__/prerender.test.ts +102 -0
- package/src/__tests__/programmatic-api.test.ts +20 -1
- package/src/__tests__/revalidation.test.ts +65 -0
- package/src/__tests__/route-lint.test.ts +79 -0
- package/src/__tests__/route-middleware.test.ts +84 -0
- package/src/__tests__/route-table.test.ts +33 -0
- package/src/__tests__/safe-validate.test.ts +96 -0
- package/src/__tests__/scanner.test.ts +46 -1
- package/src/__tests__/scroll-restoration.test.ts +66 -0
- package/src/__tests__/search-serializer.test.ts +42 -0
- package/src/__tests__/search-validation.test.ts +125 -0
- package/src/__tests__/security-fixes.test.ts +201 -0
- package/src/__tests__/security.test.ts +110 -1
- package/src/__tests__/selective-ssr.test.ts +85 -0
- package/src/__tests__/spa-mode.test.ts +77 -0
- package/src/__tests__/typed-routing.test.ts +51 -1
- package/src/__tests__/use-matches.test.ts +54 -0
- package/src/build/bundler.ts +33 -0
- package/src/build/prerender.ts +88 -0
- package/src/build/route-lint.ts +49 -0
- package/src/client/ClientRouter.tsx +339 -47
- package/src/client/cache.ts +8 -0
- package/src/client/components/Await.tsx +9 -2
- package/src/client/components/Form.tsx +23 -34
- package/src/client/components/Link.tsx +80 -9
- package/src/client/components/Outlet.tsx +8 -2
- package/src/client/components/ScrollRestoration.tsx +125 -0
- package/src/client/entry.tsx +39 -2
- package/src/client/fetcher-store.ts +61 -0
- package/src/client/form-utils.ts +3 -0
- package/src/client/hooks/useActionData.ts +7 -3
- package/src/client/hooks/useFetcher.ts +116 -33
- package/src/client/hooks/useFetchers.ts +23 -0
- package/src/client/hooks/useLoaderData.ts +8 -4
- package/src/client/hooks/useLocation.ts +27 -0
- package/src/client/hooks/useMatches.ts +32 -0
- package/src/client/hooks/useNavigate.ts +11 -6
- package/src/client/hooks/useRevalidator.ts +26 -0
- package/src/client/hooks/useSearch.ts +73 -0
- package/src/client/hooks/useSearchParams.ts +7 -2
- package/src/client/nav-utils.ts +26 -0
- package/src/client/prefetch.ts +110 -15
- package/src/client/registry.ts +24 -0
- package/src/client/revalidation.ts +25 -0
- package/src/client/router.tsx +34 -1
- package/src/client/rpc.ts +11 -1
- package/src/client/scroll-restoration.ts +48 -0
- package/src/client/search-serializer.ts +40 -0
- package/src/client/types.ts +6 -0
- package/src/codegen/module-registry.ts +13 -21
- package/src/codegen/route-codegen.ts +148 -10
- package/src/config/load.ts +22 -0
- package/src/dev/hmr-client.ts +3 -1
- package/src/dev/route-table.ts +27 -0
- package/src/dev/server.ts +106 -8
- package/src/dev/watcher.ts +25 -3
- package/src/index.ts +38 -6
- package/src/server/action-handler.ts +3 -13
- package/src/server/action-registry.ts +35 -0
- package/src/server/adapter.ts +16 -0
- package/src/server/api-route.ts +47 -0
- package/src/server/csp.ts +19 -4
- package/src/server/csrf.ts +36 -3
- package/src/server/env.ts +26 -5
- package/src/server/headers.ts +49 -0
- package/src/server/layout.ts +43 -20
- package/src/server/loader.ts +14 -8
- package/src/server/matcher.ts +29 -2
- package/src/server/matches.ts +50 -0
- package/src/server/middleware.ts +66 -0
- package/src/server/proto-guard.ts +56 -0
- package/src/server/render.ts +51 -18
- package/src/server/request-handler.ts +111 -29
- package/src/server/scanner.ts +45 -3
- package/src/server/search.ts +47 -0
- package/src/server/serve.ts +116 -4
- package/src/server/session.ts +12 -1
- package/src/server/spa.ts +62 -0
- package/src/server/stream-handler.ts +10 -1
- package/src/server/validate.ts +89 -14
- package/src/shared/context.ts +7 -0
- package/src/shared/define-actions.ts +39 -0
- package/src/shared/form-data.ts +34 -0
- package/src/shared/route-types.ts +191 -2
- package/templates/new-app/app/root.tsx +2 -1
- package/templates/new-app/bractjs.config.ts +7 -12
- package/types/config.d.ts +24 -0
- package/types/index.d.ts +182 -9
- package/types/route.d.ts +138 -3
- package/LICENSE +0 -21
- package/README.md +0 -1125
package/README.md
DELETED
|
@@ -1,1125 +0,0 @@
|
|
|
1
|
-
# BractJS
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@bractjs/bractjs)
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
|
|
6
|
-
> Production-grade SSR framework for **Bun + React 19**.
|
|
7
|
-
> File-based routing · Parallel loaders · Streaming SSR · Built-in HMR · Server Actions · Typed routes · Single-binary deploy.
|
|
8
|
-
|
|
9
|
-
## Requirements
|
|
10
|
-
|
|
11
|
-
- [Bun](https://bun.sh) ≥ 1.1 — no Node.js support
|
|
12
|
-
- React 19 (peer dependency)
|
|
13
|
-
|
|
14
|
-
This README is a **step-by-step guide to every function and feature** BractJS exports. Each section is self-contained and ordered from "first app" to "advanced". Every symbol shown here is a real export from `@bractjs/bractjs` (see [src/index.ts](src/index.ts)).
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## Table of Contents
|
|
19
|
-
|
|
20
|
-
1. [Install & create an app](#1-install--create-an-app)
|
|
21
|
-
2. [Project structure](#2-project-structure)
|
|
22
|
-
3. [The root layout (`app/root.tsx`)](#3-the-root-layout-approotsx)
|
|
23
|
-
4. [File-based routing](#4-file-based-routing)
|
|
24
|
-
5. [Route module API: `loader`, `action`, `meta`, `beforeLoad`, `ErrorBoundary`, `default`](#5-route-module-api)
|
|
25
|
-
6. [Response helpers: `json`, `redirect`, `error`, `HttpError`](#6-response-helpers)
|
|
26
|
-
7. [Per-route context: `defineContext`](#7-per-route-context-definecontext)
|
|
27
|
-
8. [Streaming data: `defer`, `Deferred`, `isDeferred`, `<Await>`](#8-streaming-data)
|
|
28
|
-
9. [Client hooks](#9-client-hooks)
|
|
29
|
-
10. [Client components: `<Outlet>`, `<Link>`, `<Form>`, `<Scripts>`, `<LiveReload>`, `<Image>`](#10-client-components)
|
|
30
|
-
11. [Server Actions (`"use server"`) & client-only (`"use client"`)](#11-server-actions--client-components)
|
|
31
|
-
12. [Typed API routes: `route` + `createClient`](#12-typed-api-routes)
|
|
32
|
-
13. [Input validation: `validate`](#13-input-validation-validate)
|
|
33
|
-
14. [Middleware: `pipeline`, `requestLogger`, `cors`, `authGuard`, `csp`](#14-middleware)
|
|
34
|
-
15. [Sessions: `createCookieSession`](#15-sessions)
|
|
35
|
-
16. [Lifecycle hooks: `defineLifecycle`](#16-lifecycle-hooks)
|
|
36
|
-
17. [Environment variables & `*.server.ts`](#17-environment-variables)
|
|
37
|
-
18. [Typed routes](#18-typed-routes)
|
|
38
|
-
19. [Internationalization (i18n) utilities](#19-internationalization-utilities)
|
|
39
|
-
20. [Image optimization (`<Image>` + `/_image`)](#20-image-optimization)
|
|
40
|
-
21. [Build & run: CLI + programmatic API (`createDevServer`, `runBuild`, `loadUserConfig`)](#21-build--run)
|
|
41
|
-
22. [Single-binary deployment (`bun build --compile`)](#22-single-binary-deployment)
|
|
42
|
-
23. [Custom adapters (`BunAdapter`, Cloudflare)](#23-custom-adapters)
|
|
43
|
-
24. [Build plugins (for custom `Bun.build`)](#24-build-plugins)
|
|
44
|
-
25. [Configuration reference](#25-configuration-reference)
|
|
45
|
-
26. [Full export index](#26-full-export-index)
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## 1. Install & create an app
|
|
50
|
-
|
|
51
|
-
BractJS requires [Bun](https://bun.sh). There is no Node.js runtime path.
|
|
52
|
-
|
|
53
|
-
```sh
|
|
54
|
-
# Scaffold a new app
|
|
55
|
-
bunx bractjs new my-app
|
|
56
|
-
cd my-app
|
|
57
|
-
|
|
58
|
-
# Start the dev server (HMR on http://localhost:3000)
|
|
59
|
-
bun run dev
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
`bractjs new <name>` copies the scaffold template, runs `bun install`, and seeds `app/_generated/` so the single-binary entry typechecks before your first build.
|
|
63
|
-
|
|
64
|
-
Add it to an existing project instead:
|
|
65
|
-
|
|
66
|
-
```sh
|
|
67
|
-
bun add @bractjs/bractjs react react-dom
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
`react` and `react-dom` v19 are **peer dependencies** — BractJS ships zero other runtime deps.
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
## 2. Project structure
|
|
75
|
-
|
|
76
|
-
```
|
|
77
|
-
my-app/
|
|
78
|
-
├── app/
|
|
79
|
-
│ ├── root.tsx # required — the <html> document shell
|
|
80
|
-
│ ├── server.ts # single-binary entry (bun build --compile)
|
|
81
|
-
│ ├── lifecycle.ts # optional — onStart / onShutdown / onError
|
|
82
|
-
│ ├── route-types.gen.ts # generated by `bractjs codegen`
|
|
83
|
-
│ ├── _generated/ # generated by `bractjs codegen:registry` / `:manifest`
|
|
84
|
-
│ ├── actions.ts # "use server" actions (optional)
|
|
85
|
-
│ └── routes/
|
|
86
|
-
│ ├── _index.tsx # → /
|
|
87
|
-
│ ├── about.tsx # → /about
|
|
88
|
-
│ ├── blog/
|
|
89
|
-
│ │ ├── layout.tsx # wraps /blog/*
|
|
90
|
-
│ │ ├── _index.tsx # → /blog
|
|
91
|
-
│ │ └── [id].tsx # → /blog/:id
|
|
92
|
-
│ └── docs/
|
|
93
|
-
│ └── [...slug].tsx # → /docs/* (catch-all)
|
|
94
|
-
├── public/ # static assets, served at /public/*
|
|
95
|
-
├── bractjs.config.ts # optional config (see §25)
|
|
96
|
-
└── build/ # generated — do not edit
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Defaults: `appDir="./app"`, `publicDir="./public"`, `buildDir="./build"`, `port=3000`. All overridable (§25).
|
|
100
|
-
|
|
101
|
-
---
|
|
102
|
-
|
|
103
|
-
## 3. The root layout (`app/root.tsx`)
|
|
104
|
-
|
|
105
|
-
**Required.** It provides the `<html>` document shell and is always rendered. Use the `<Outlet>`, `<Scripts>`, and `<LiveReload>` components from the package.
|
|
106
|
-
|
|
107
|
-
```tsx
|
|
108
|
-
// app/root.tsx
|
|
109
|
-
import { Outlet, Scripts, LiveReload } from "@bractjs/bractjs";
|
|
110
|
-
|
|
111
|
-
export function meta() {
|
|
112
|
-
return [
|
|
113
|
-
{ title: "My App" },
|
|
114
|
-
{ name: "viewport", content: "width=device-width, initial-scale=1" },
|
|
115
|
-
];
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
export default function Root() {
|
|
119
|
-
return (
|
|
120
|
-
<html lang="en">
|
|
121
|
-
<head>
|
|
122
|
-
<meta charSet="utf-8" />
|
|
123
|
-
{/* BractJS hoists <title>/<meta> from every route's meta() into <head> */}
|
|
124
|
-
</head>
|
|
125
|
-
<body>
|
|
126
|
-
<Outlet /> {/* renders the matched route tree */}
|
|
127
|
-
<Scripts /> {/* injects the client bundle + bootstrap data */}
|
|
128
|
-
<LiveReload /> {/* dev-only HMR client; no-op in production */}
|
|
129
|
-
</body>
|
|
130
|
-
</html>
|
|
131
|
-
);
|
|
132
|
-
}
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
**Step by step:**
|
|
136
|
-
|
|
137
|
-
1. `export default function Root()` returns the full `<html>` document.
|
|
138
|
-
2. Put `<Outlet />` where the page content should render.
|
|
139
|
-
3. Put `<Scripts />` at the end of `<body>` — it's a marker the SSR pipeline replaces with the hashed client entry + `window.__BRACTJS_DATA__`.
|
|
140
|
-
4. `<LiveReload />` renders an HMR client script in dev and `null` in production.
|
|
141
|
-
5. Optionally `export function meta()` for site-wide defaults (route `meta()` overrides per descriptor).
|
|
142
|
-
|
|
143
|
-
> `<title>`/`<meta>` tags from any route's `meta()` are rendered into `<head>` via React 19 document-metadata hoisting — you do not place them manually.
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
## 4. File-based routing
|
|
148
|
-
|
|
149
|
-
Drop a file in `app/routes/`; it becomes a route. BractJS scans at startup and builds a trie.
|
|
150
|
-
|
|
151
|
-
| File | URL |
|
|
152
|
-
|------|-----|
|
|
153
|
-
| `routes/_index.tsx` | `/` |
|
|
154
|
-
| `routes/about.tsx` | `/about` |
|
|
155
|
-
| `routes/blog/_index.tsx` | `/blog` |
|
|
156
|
-
| `routes/blog/[id].tsx` | `/blog/:id` |
|
|
157
|
-
| `routes/docs/[...slug].tsx` | `/docs/*` (catch-all) |
|
|
158
|
-
| `routes/blog/layout.tsx` | wraps all `/blog/*` routes |
|
|
159
|
-
|
|
160
|
-
- `[param]` → a dynamic segment, read via `useParams()` / `params` arg.
|
|
161
|
-
- `[...name]` → a catch-all; the rest of the path lands in `params.name`.
|
|
162
|
-
- `layout.tsx` in any directory wraps every route under it (layouts nest: `root → blog/layout → blog/[id]`).
|
|
163
|
-
- Match priority per segment: **static > dynamic > catch-all**.
|
|
164
|
-
|
|
165
|
-
No registration step — the file IS the route.
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## 5. Route module API
|
|
170
|
-
|
|
171
|
-
Every file in `app/routes/` (and `root.tsx`/`layout.tsx`) may export any combination of these. Import the arg types from the package.
|
|
172
|
-
|
|
173
|
-
```tsx
|
|
174
|
-
import type { LoaderArgs, ActionArgs, MetaArgs } from "@bractjs/bractjs";
|
|
175
|
-
import { redirect, json, HttpError } from "@bractjs/bractjs";
|
|
176
|
-
|
|
177
|
-
// 1) loader — runs on every GET. Return value → useLoaderData().
|
|
178
|
-
export async function loader({ request, params, context }: LoaderArgs) {
|
|
179
|
-
const post = await db.post.findById(params.id);
|
|
180
|
-
if (!post) throw new HttpError(404, "Not found"); // → 404 page
|
|
181
|
-
return { post };
|
|
182
|
-
}
|
|
183
|
-
export type LoaderData = Awaited<ReturnType<typeof loader>>;
|
|
184
|
-
|
|
185
|
-
// 2) action — runs on POST / PUT / DELETE / PATCH.
|
|
186
|
-
export async function action({ request, params, context, formData }: ActionArgs) {
|
|
187
|
-
await db.post.update(params.id, { title: formData.get("title") as string });
|
|
188
|
-
return redirect("/blog");
|
|
189
|
-
}
|
|
190
|
-
|
|
191
|
-
// 3) meta — SSR <title> / <meta>. Receives this route's loaderData slice.
|
|
192
|
-
export function meta({ loaderData, params }: MetaArgs<LoaderData>) {
|
|
193
|
-
return [
|
|
194
|
-
{ title: loaderData.post.title },
|
|
195
|
-
{ name: "description", content: loaderData.post.excerpt },
|
|
196
|
-
{ property: "og:title", content: loaderData.post.title },
|
|
197
|
-
];
|
|
198
|
-
}
|
|
199
|
-
|
|
200
|
-
// 4) beforeLoad — auth/redirect gate. Runs BEFORE loaders, on full-page GET
|
|
201
|
-
// AND the /_data soft-nav endpoint. Return a Response to short-circuit.
|
|
202
|
-
export function beforeLoad({ context, params, location }) {
|
|
203
|
-
if (!context.user) {
|
|
204
|
-
return redirect(`/login?next=${encodeURIComponent(location.pathname)}`);
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
|
|
208
|
-
// 5) ErrorBoundary — renders when this segment's loader/component throws.
|
|
209
|
-
export function ErrorBoundary({ error }: { error: unknown }) {
|
|
210
|
-
return <p>Something broke: {error instanceof Error ? error.message : String(error)}</p>;
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
// 6) default — the page component (required for a renderable route).
|
|
214
|
-
export default function BlogPost() {
|
|
215
|
-
const { post } = useLoaderData<LoaderData>();
|
|
216
|
-
return <article><h1>{post.title}</h1></article>;
|
|
217
|
-
}
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
**Execution order for a request:**
|
|
221
|
-
|
|
222
|
-
```
|
|
223
|
-
beforeLoad → (action, if mutating method) → loaders (root + layouts + route, in parallel) → render
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
- **Loaders run concurrently** (root, every layout, and the route loader all in one `Promise.all`).
|
|
227
|
-
- A loader that throws an `HttpError`/redirect `Response` is intentional control flow. Any *other* thrown error is caught, sanitized (generic message in production, full message+stack only when `NODE_ENV=development`), and rendered via the nearest `ErrorBoundary`.
|
|
228
|
-
|
|
229
|
-
> **Security:** put auth checks in `beforeLoad` (per route) or middleware (cross-cutting) — never in a component. `/_data` (used by `<Link>` soft-nav) runs `beforeLoad` and the loader, so a component-only check would still leak loader JSON. See §14.
|
|
230
|
-
|
|
231
|
-
---
|
|
232
|
-
|
|
233
|
-
## 6. Response helpers
|
|
234
|
-
|
|
235
|
-
Imported from `@bractjs/bractjs`.
|
|
236
|
-
|
|
237
|
-
```ts
|
|
238
|
-
import { json, redirect, error, HttpError, isRedirect, isHttpError } from "@bractjs/bractjs";
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
### `json(data, init?)`
|
|
242
|
-
Serialize a value as `application/json`.
|
|
243
|
-
```ts
|
|
244
|
-
return json({ ok: true }, { status: 201 });
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
### `redirect(url, status?, headers?, options?)`
|
|
248
|
-
Throw or return a redirect. **Open-redirect safe by default** — rejects `//evil.com`, `/\evil`, `https://…`, `javascript:` unless you pass `{ allowExternal: true }`.
|
|
249
|
-
```ts
|
|
250
|
-
return redirect("/dashboard"); // 302
|
|
251
|
-
return redirect("/login", 303); // custom status
|
|
252
|
-
return redirect("/x", 302, { "Set-Cookie": cookie }); // with headers
|
|
253
|
-
return redirect("https://other.com", 302, undefined, { allowExternal: true });
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
### `error(message, status?)`
|
|
257
|
-
Convenience JSON error: `{ "error": message }` with the given status (default 500).
|
|
258
|
-
```ts
|
|
259
|
-
return error("Bad Request", 400);
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
### `HttpError` & `BractJSError`
|
|
263
|
-
Throw a typed HTTP error from a loader/action. The framework converts it to a response with that status (and a default status text if you omit the message).
|
|
264
|
-
```ts
|
|
265
|
-
throw new HttpError(403); // → 403 Forbidden
|
|
266
|
-
throw new HttpError(404, "No such post"); // → 404 with custom message
|
|
267
|
-
```
|
|
268
|
-
`isRedirect(value)` / `isHttpError(value)` / `isBractJSError(value)` are type guards if you handle errors manually.
|
|
269
|
-
|
|
270
|
-
---
|
|
271
|
-
|
|
272
|
-
## 7. Per-route context: `defineContext`
|
|
273
|
-
|
|
274
|
-
A route can compute request-scoped data once and share it with all its loaders/actions via the `context` argument. Middleware can also populate `context` (§14) — `defineContext` is the per-route version.
|
|
275
|
-
|
|
276
|
-
```ts
|
|
277
|
-
// app/routes/dashboard.tsx
|
|
278
|
-
import { defineContext } from "@bractjs/bractjs";
|
|
279
|
-
import { getUser } from "../auth.server.ts";
|
|
280
|
-
|
|
281
|
-
export const context = defineContext(async ({ request, params }) => ({
|
|
282
|
-
user: await getUser(request),
|
|
283
|
-
}));
|
|
284
|
-
|
|
285
|
-
export function beforeLoad({ context }) {
|
|
286
|
-
if (!context.user) return redirect("/login");
|
|
287
|
-
}
|
|
288
|
-
|
|
289
|
-
export async function loader({ context }) {
|
|
290
|
-
return { name: context.user.name };
|
|
291
|
-
}
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
The factory runs before `beforeLoad` and its result is merged into `context` for `beforeLoad`, `loader`, and `action` on that route.
|
|
295
|
-
|
|
296
|
-
---
|
|
297
|
-
|
|
298
|
-
## 8. Streaming data
|
|
299
|
-
|
|
300
|
-
Stream slow data without blocking the initial HTML.
|
|
301
|
-
|
|
302
|
-
```ts
|
|
303
|
-
import { defer, Deferred, isDeferred } from "@bractjs/bractjs";
|
|
304
|
-
import { Await } from "@bractjs/bractjs";
|
|
305
|
-
import { Suspense } from "react";
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
### `defer(data)`
|
|
309
|
-
Wraps each `Promise` field in a `Deferred`; non-promise fields pass through. Awaited fields are in the initial HTML; promises stream after.
|
|
310
|
-
|
|
311
|
-
```tsx
|
|
312
|
-
export async function loader({ params }: LoaderArgs) {
|
|
313
|
-
return defer({
|
|
314
|
-
post: await db.post.findById(params.id), // awaited → initial HTML
|
|
315
|
-
comments: db.comments.forPost(params.id), // Promise → streamed
|
|
316
|
-
});
|
|
317
|
-
}
|
|
318
|
-
|
|
319
|
-
export default function BlogPost() {
|
|
320
|
-
const { post, comments } = useLoaderData<LoaderData>();
|
|
321
|
-
return (
|
|
322
|
-
<article>
|
|
323
|
-
<h1>{post.title}</h1>
|
|
324
|
-
<Suspense fallback={<p>Loading comments…</p>}>
|
|
325
|
-
<Await resolve={comments}>
|
|
326
|
-
{(c) => <CommentList comments={c} />}
|
|
327
|
-
</Await>
|
|
328
|
-
</Suspense>
|
|
329
|
-
</article>
|
|
330
|
-
);
|
|
331
|
-
}
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
### `<Await resolve={promise} fallback={…}>{(data) => …}</Await>`
|
|
335
|
-
Unwraps a promise with React 19's `use()` inside its own `<Suspense>`. `isDeferred(value)` and the `Deferred` class are exported if you need to detect/construct deferred values manually.
|
|
336
|
-
|
|
337
|
-
---
|
|
338
|
-
|
|
339
|
-
## 9. Client hooks
|
|
340
|
-
|
|
341
|
-
All hooks are SSR-safe (they return sensible values during SSR) and imported from `@bractjs/bractjs`.
|
|
342
|
-
|
|
343
|
-
### `useLoaderData<T>()` → `T`
|
|
344
|
-
The current route's loader return value.
|
|
345
|
-
```ts
|
|
346
|
-
const { post } = useLoaderData<LoaderData>();
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
### `useActionData<T>()` → `T | null`
|
|
350
|
-
The most recent action return value (null until an action runs).
|
|
351
|
-
```ts
|
|
352
|
-
const result = useActionData<{ error?: string }>();
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
### `useParams<T>()` → `T`
|
|
356
|
-
URL dynamic params. Pass the **route pattern** as a generic to type the result against your codegen'd routes (see §18); an object shape also works.
|
|
357
|
-
```ts
|
|
358
|
-
const { id } = useParams<"/blog/:id">(); // { id: string } — typed from routes
|
|
359
|
-
const { id } = useParams<{ id: string }>(); // or a hand-written shape
|
|
360
|
-
```
|
|
361
|
-
> The pattern is supplied by the caller because the framework can't infer the active route at the type level (React Router's `useParams` works the same way).
|
|
362
|
-
|
|
363
|
-
### `useNavigation()` → `{ state }`
|
|
364
|
-
`"idle" | "loading" | "submitting"`.
|
|
365
|
-
```ts
|
|
366
|
-
const { state } = useNavigation();
|
|
367
|
-
if (state === "loading") return <Spinner />;
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
### `useNavigate()` → `(to, { params? }) => Promise<void>`
|
|
371
|
-
Imperative soft navigation — the counterpart to `<Link>`. `to` autocompletes your routes (after codegen, §18) and `params` is typed per route; any string is still accepted.
|
|
372
|
-
```ts
|
|
373
|
-
const navigate = useNavigate();
|
|
374
|
-
await navigate("/blog/:id", { params: { id: "42" } }); // typed
|
|
375
|
-
await navigate("/about"); // static
|
|
376
|
-
await navigate(`/blog/${id}`); // built string (also fine)
|
|
377
|
-
```
|
|
378
|
-
|
|
379
|
-
### `useSearchParams<T>()` → `{ searchParams, getParam, setSearchParams }`
|
|
380
|
-
Read/write URL query params; writing triggers a soft-nav loader re-run. Pass the route pattern as a generic to type the result against `RouteSearchParamsMap` (augment it per route, §18); an object shape also works.
|
|
381
|
-
```ts
|
|
382
|
-
const { searchParams, getParam, setSearchParams } = useSearchParams<"/blog/:id">();
|
|
383
|
-
const q = getParam("q"); // string | null
|
|
384
|
-
setSearchParams({ q: "bun" }); // replace all params
|
|
385
|
-
setSearchParams((prev) => { prev.set("page", "2"); return prev; }); // update
|
|
386
|
-
```
|
|
387
|
-
|
|
388
|
-
### `useFetcher()` → `{ data, state, load, submit }`
|
|
389
|
-
Background fetch without navigating.
|
|
390
|
-
```ts
|
|
391
|
-
const fetcher = useFetcher();
|
|
392
|
-
await fetcher.load("/products?q=bun"); // GET loader data
|
|
393
|
-
await fetcher.submit("/cart", { method: "post", body: { id: "1" } });
|
|
394
|
-
```
|
|
395
|
-
|
|
396
|
-
### `useFetcher<T>({ stream: true })` → `{ connect }`
|
|
397
|
-
Consume an async-generator server action as an SSE stream.
|
|
398
|
-
```ts
|
|
399
|
-
const { connect } = useFetcher<string>({ stream: true });
|
|
400
|
-
for await (const chunk of connect(actionId)) { /* … */ }
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
### `useBlocker(shouldBlock)`
|
|
404
|
-
Prompt before leaving when there are unsaved changes (intercepts back/forward and `<Link>` navigations).
|
|
405
|
-
```ts
|
|
406
|
-
useBlocker(() => formIsDirty);
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
### `useLocale(defaultLocale?)` → `string` and `useLocalizedLink(defaultLocale?)` → `(path) => string`
|
|
410
|
-
For i18n prefix routing (§19).
|
|
411
|
-
```ts
|
|
412
|
-
const locale = useLocale("en"); // reads params.locale
|
|
413
|
-
const localized = useLocalizedLink("en");
|
|
414
|
-
<Link to={localized("/about")} /> // → /en/about
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
---
|
|
418
|
-
|
|
419
|
-
## 10. Client components
|
|
420
|
-
|
|
421
|
-
### `<Outlet />`
|
|
422
|
-
Renders the matched child route inside a layout (or the route tree inside `root.tsx`).
|
|
423
|
-
```tsx
|
|
424
|
-
export default function BlogLayout() {
|
|
425
|
-
return <div><nav>Blog</nav><Outlet /></div>;
|
|
426
|
-
}
|
|
427
|
-
```
|
|
428
|
-
|
|
429
|
-
### `<Link to params? prefetch? viewTransition?>`
|
|
430
|
-
Soft-navigates without a full reload. After codegen (§18), `to` autocompletes your routes; for a dynamic route pass typed `params`. Building the URL yourself still works, so existing links need no changes.
|
|
431
|
-
```tsx
|
|
432
|
-
<Link to="/blog/:id" params={{ id: "42" }}>Read</Link> {/* typed route + params */}
|
|
433
|
-
<Link to={`/blog/${id}`}>Read</Link> {/* built string — also fine */}
|
|
434
|
-
<Link to="/about" prefetch="hover">About</Link> {/* preload chunk + loader on hover */}
|
|
435
|
-
<Link to="/gallery" viewTransition>Gallery</Link> {/* use View Transitions API */}
|
|
436
|
-
```
|
|
437
|
-
Modifier-clicks (ctrl/cmd/shift/alt) fall back to native browser navigation.
|
|
438
|
-
|
|
439
|
-
### `<Form method action?>`
|
|
440
|
-
Fetch-based submission that re-runs the current route's loader after the action.
|
|
441
|
-
```tsx
|
|
442
|
-
<Form method="post">
|
|
443
|
-
<input name="title" />
|
|
444
|
-
<button type="submit">Create</button>
|
|
445
|
-
</Form>
|
|
446
|
-
<Form method="post" action="/blog/new">…</Form>
|
|
447
|
-
```
|
|
448
|
-
Submits as `multipart/form-data` with the `X-BractJS-Action` header (CSRF gate). If the action returns a redirect, the form follows it.
|
|
449
|
-
|
|
450
|
-
### `<Scripts />` and `<LiveReload />`
|
|
451
|
-
Markers used inside `root.tsx` (§3). `<Scripts />` is where the client bundle + bootstrap data go; `<LiveReload />` is the dev-only HMR client.
|
|
452
|
-
|
|
453
|
-
### `<Image />`
|
|
454
|
-
Responsive, format-converted images via the built-in `/_image` endpoint — see §20.
|
|
455
|
-
|
|
456
|
-
---
|
|
457
|
-
|
|
458
|
-
## 11. Server Actions & Client Components
|
|
459
|
-
|
|
460
|
-
### `"use server"` — Server Actions
|
|
461
|
-
|
|
462
|
-
Mark a file's exports as server actions by making `"use server"` the first line. On the **client**, imports become `fetch("/_action?id=<hash>")` proxies; on the **server**, the real function runs. Action IDs are `SHA-256(appDir-relative-path + "#" + name)`.
|
|
463
|
-
|
|
464
|
-
```ts
|
|
465
|
-
// app/actions.ts
|
|
466
|
-
"use server";
|
|
467
|
-
|
|
468
|
-
export async function createPost(formData: FormData) {
|
|
469
|
-
const title = formData.get("title") as string;
|
|
470
|
-
await db.insert(posts).values({ title });
|
|
471
|
-
return { ok: true };
|
|
472
|
-
}
|
|
473
|
-
|
|
474
|
-
export async function deletePost(id: string) {
|
|
475
|
-
await db.delete(posts).where(eq(posts.id, id));
|
|
476
|
-
}
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
```tsx
|
|
480
|
-
// app/routes/new.tsx — import as normal; the client bundle gets a fetch proxy
|
|
481
|
-
import { createPost } from "../actions.ts";
|
|
482
|
-
|
|
483
|
-
export default function NewPost() {
|
|
484
|
-
return (
|
|
485
|
-
<form action={createPost}>
|
|
486
|
-
<input name="title" />
|
|
487
|
-
<button type="submit">Create</button>
|
|
488
|
-
</form>
|
|
489
|
-
);
|
|
490
|
-
}
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
- Accepts a single `FormData` (sent as `multipart/form-data`) **or** a JSON-serializable argument array.
|
|
494
|
-
- Unknown action IDs return 404 — only functions registered at startup are callable.
|
|
495
|
-
- Bodies are size-capped (1 MiB JSON) and prototype-pollution scanned.
|
|
496
|
-
|
|
497
|
-
**Streaming server actions** (async generators) are consumed with `useFetcher({ stream: true })` (§9) over `/_stream`. The endpoint requires the `X-BractJS-Action` header (set automatically by the client).
|
|
498
|
-
|
|
499
|
-
### `"use client"` — Client-Only Components
|
|
500
|
-
|
|
501
|
-
Mark a component browser-only. During server builds the module is stubbed to `null` to prevent `window`/`document`/`localStorage` crashes during SSR.
|
|
502
|
-
|
|
503
|
-
```tsx
|
|
504
|
-
// app/components/Counter.tsx
|
|
505
|
-
"use client";
|
|
506
|
-
import { useState } from "react";
|
|
507
|
-
|
|
508
|
-
export function Counter() {
|
|
509
|
-
const [n, setN] = useState(0);
|
|
510
|
-
return <button onClick={() => setN(n + 1)}>Count: {n}</button>;
|
|
511
|
-
}
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
---
|
|
515
|
-
|
|
516
|
-
## 12. Typed API routes
|
|
517
|
-
|
|
518
|
-
Define type-safe JSON endpoints under `/api/*` with `route`, and call them with a fully-typed `createClient`.
|
|
519
|
-
|
|
520
|
-
### Define routes with `route(method, path, handler)`
|
|
521
|
-
|
|
522
|
-
```ts
|
|
523
|
-
// app/api/users.ts
|
|
524
|
-
import { route } from "@bractjs/bractjs";
|
|
525
|
-
import { db } from "../db.server.ts";
|
|
526
|
-
|
|
527
|
-
export const listUsers = route("GET", "/api/users", async () => {
|
|
528
|
-
return db.users.findAll();
|
|
529
|
-
});
|
|
530
|
-
|
|
531
|
-
export const createUser = route("POST", "/api/users", async (input: { name: string }) => {
|
|
532
|
-
return db.users.create(input);
|
|
533
|
-
});
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
- `GET`/`DELETE`: no body parsed. `POST`/`PUT`/`PATCH`: JSON or form body parsed into `input`.
|
|
537
|
-
- Bodies are capped at 1 MiB. Errors return a generic 500 in production (full message in dev).
|
|
538
|
-
- Handlers also receive the raw `Request` as the 2nd arg.
|
|
539
|
-
- `:param` segments match any non-empty value; **read and validate params from `request.url` yourself** (they aren't injected into `input`).
|
|
540
|
-
|
|
541
|
-
### Call them with `createClient<AppApiRoutes>()`
|
|
542
|
-
|
|
543
|
-
```ts
|
|
544
|
-
import { createClient } from "@bractjs/bractjs";
|
|
545
|
-
import type { AppApiRoutes } from "@bractjs/bractjs"; // union of your route defs
|
|
546
|
-
|
|
547
|
-
const client = createClient<AppApiRoutes>(); // optional baseUrl arg
|
|
548
|
-
const users = await client["/api/users"].GET(); // typed output
|
|
549
|
-
await client["/api/users"].POST({ name: "Alice" }); // typed input
|
|
550
|
-
```
|
|
551
|
-
|
|
552
|
-
The proxy builds `METHOD path` from the property chain. Non-2xx responses throw an `Error` with `.status` and `.response` attached.
|
|
553
|
-
|
|
554
|
-
---
|
|
555
|
-
|
|
556
|
-
## 13. Input validation: `validate`
|
|
557
|
-
|
|
558
|
-
Validate `FormData` or a plain object against any **Zod- or Valibot-compatible** schema (anything with `.safeParse()` or `.parse()`).
|
|
559
|
-
|
|
560
|
-
```ts
|
|
561
|
-
import { validate } from "@bractjs/bractjs";
|
|
562
|
-
import { z } from "zod";
|
|
563
|
-
|
|
564
|
-
const Schema = z.object({ title: z.string().min(1), tags: z.array(z.string()) });
|
|
565
|
-
|
|
566
|
-
export async function action({ formData }: ActionArgs) {
|
|
567
|
-
// Throws a 400 Response with { errors: { field: [msgs] } } on failure.
|
|
568
|
-
const data = await validate(Schema, formData);
|
|
569
|
-
await db.post.create(data); // data is fully typed + coerced
|
|
570
|
-
}
|
|
571
|
-
```
|
|
572
|
-
|
|
573
|
-
- Repeated `FormData` keys become arrays automatically.
|
|
574
|
-
- On failure it throws a `Response.json({ errors }, { status: 400 })`. The exported `ValidationError` type and `FieldErrors` shape describe the structure.
|
|
575
|
-
|
|
576
|
-
---
|
|
577
|
-
|
|
578
|
-
## 14. Middleware
|
|
579
|
-
|
|
580
|
-
Middleware runs **before routing** on the module-level `pipeline` singleton. Each middleware gets `(ctx, next)` and returns a `Response`. `ctx.context` is threaded into every loader/action.
|
|
581
|
-
|
|
582
|
-
```ts
|
|
583
|
-
import { pipeline, requestLogger, cors, authGuard, csp } from "@bractjs/bractjs";
|
|
584
|
-
import type { MiddlewareFn } from "@bractjs/bractjs";
|
|
585
|
-
|
|
586
|
-
pipeline
|
|
587
|
-
.use(requestLogger())
|
|
588
|
-
.use(cors({ origin: "https://myapp.com" }))
|
|
589
|
-
.use(csp())
|
|
590
|
-
.use(authGuard({ session }));
|
|
591
|
-
```
|
|
592
|
-
|
|
593
|
-
### Built-in middleware
|
|
594
|
-
|
|
595
|
-
| Middleware | What it does |
|
|
596
|
-
|---|---|
|
|
597
|
-
| `requestLogger()` | Logs `[METHOD] /path → status in Xms`. Never logs the query string or headers (token-leak safe). |
|
|
598
|
-
| `cors(options)` | Sets CORS headers, handles `OPTIONS` preflight (204), always sets `Vary: Origin`, refuses `credentials:true` + `origin:"*"`. |
|
|
599
|
-
| `authGuard(options)` | Reads the session, sets `ctx.context.user`; with `required:true` returns 401 when unauthenticated. |
|
|
600
|
-
| `csp(options?)` | Opt-in nonce-based Content-Security-Policy (see below). |
|
|
601
|
-
|
|
602
|
-
**`cors(options)`** — `{ origin: string | string[]; methods?: string[]; credentials?: boolean }`:
|
|
603
|
-
```ts
|
|
604
|
-
pipeline.use(cors({ origin: ["https://a.com", "https://b.com"], credentials: true }));
|
|
605
|
-
```
|
|
606
|
-
|
|
607
|
-
**`authGuard(options)`** — `{ session: SessionStorageLike; required?: boolean }`:
|
|
608
|
-
```ts
|
|
609
|
-
pipeline.use(authGuard({ session, required: true })); // 401 if no session.user
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
**`csp(options?)`** — generates a per-request nonce, applies it to the scripts BractJS injects (via `renderToReadableStream`'s `nonce`), and sets the CSP header:
|
|
613
|
-
```ts
|
|
614
|
-
pipeline.use(csp({
|
|
615
|
-
directives: { "img-src": "'self' data: https://cdn.example", "frame-ancestors": "'none'" },
|
|
616
|
-
reportOnly: false, // true → Content-Security-Policy-Report-Only
|
|
617
|
-
}));
|
|
618
|
-
```
|
|
619
|
-
Read the nonce inside a component/middleware with `getCspNonce(context)` (key: `CSP_NONCE_KEY`) to nonce your own inline scripts.
|
|
620
|
-
|
|
621
|
-
### Custom middleware
|
|
622
|
-
|
|
623
|
-
```ts
|
|
624
|
-
import type { MiddlewareFn } from "@bractjs/bractjs";
|
|
625
|
-
|
|
626
|
-
const trace: MiddlewareFn = async (ctx, next) => {
|
|
627
|
-
ctx.context.requestId = crypto.randomUUID();
|
|
628
|
-
const res = await next();
|
|
629
|
-
res.headers.set("X-Request-Id", ctx.context.requestId as string);
|
|
630
|
-
return res;
|
|
631
|
-
};
|
|
632
|
-
pipeline.use(trace);
|
|
633
|
-
```
|
|
634
|
-
|
|
635
|
-
You can also construct an isolated `new MiddlewarePipeline()` and `.run(ctx, handler)` it yourself (used internally and in tests).
|
|
636
|
-
|
|
637
|
-
---
|
|
638
|
-
|
|
639
|
-
## 15. Sessions
|
|
640
|
-
|
|
641
|
-
Signed, tamper-proof cookie sessions (HMAC-SHA256, constant-time verify, secret rotation).
|
|
642
|
-
|
|
643
|
-
```ts
|
|
644
|
-
import { createCookieSession } from "@bractjs/bractjs";
|
|
645
|
-
|
|
646
|
-
const session = createCookieSession({
|
|
647
|
-
name: "__session",
|
|
648
|
-
secrets: [Bun.env.SESSION_SECRET!], // first signs; all verify (rotate by prepending)
|
|
649
|
-
maxAge: 60 * 60 * 24 * 7, // seconds; 1 week
|
|
650
|
-
secure: true, // false only for local HTTP dev
|
|
651
|
-
sameSite: "Lax", // "Strict" | "Lax" | "None"
|
|
652
|
-
});
|
|
653
|
-
```
|
|
654
|
-
|
|
655
|
-
Read in a loader, write in an action:
|
|
656
|
-
|
|
657
|
-
```ts
|
|
658
|
-
export async function loader({ request }: LoaderArgs) {
|
|
659
|
-
const s = await session.getSession(request.headers.get("Cookie"));
|
|
660
|
-
return { user: s.get("user") };
|
|
661
|
-
}
|
|
662
|
-
|
|
663
|
-
export async function action({ request }: ActionArgs) {
|
|
664
|
-
const s = await session.getSession(request.headers.get("Cookie"));
|
|
665
|
-
s.set("user", { id: 1, name: "Alice" }); // also: s.get, s.has, s.delete
|
|
666
|
-
return redirect("/dashboard", {
|
|
667
|
-
headers: { "Set-Cookie": await session.commitSession(s) }, // opt: { maxAge }
|
|
668
|
-
});
|
|
669
|
-
}
|
|
670
|
-
```
|
|
671
|
-
|
|
672
|
-
- Each secret must be ≥16 chars; `secrets` must be non-empty (throws otherwise).
|
|
673
|
-
- Tampered cookies are silently rejected → empty session.
|
|
674
|
-
- Generate a secret: `openssl rand -base64 32`.
|
|
675
|
-
|
|
676
|
-
---
|
|
677
|
-
|
|
678
|
-
## 16. Lifecycle hooks: `defineLifecycle`
|
|
679
|
-
|
|
680
|
-
Run code on server start, shutdown, and unexpected errors. Shutdown fires on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, uncaught exceptions).
|
|
681
|
-
|
|
682
|
-
```ts
|
|
683
|
-
// app/lifecycle.ts
|
|
684
|
-
import { defineLifecycle } from "@bractjs/bractjs";
|
|
685
|
-
import { db } from "./db.server.ts";
|
|
686
|
-
|
|
687
|
-
export default defineLifecycle({
|
|
688
|
-
async onStart() { await db.connect(); },
|
|
689
|
-
async onShutdown(){ await db.disconnect(); },
|
|
690
|
-
onError(err, request) {
|
|
691
|
-
Sentry.captureException(err, { extra: { url: request?.url } });
|
|
692
|
-
},
|
|
693
|
-
});
|
|
694
|
-
```
|
|
695
|
-
|
|
696
|
-
| Hook | When |
|
|
697
|
-
|------|------|
|
|
698
|
-
| `onStart` | Once, after the server starts listening. |
|
|
699
|
-
| `onShutdown` | Before exit — any signal, programmatic `stop()`, or uncaught exception. |
|
|
700
|
-
| `onError` | Every unexpected error (loader/action throws, uncaught exceptions). Redirects and `HttpError`s are intentional control flow and are **not** reported. `request` is `undefined` for process-level exceptions. |
|
|
701
|
-
|
|
702
|
-
- **Dev** picks up `app/lifecycle.ts` automatically.
|
|
703
|
-
- **Production**: spread into `createServer()`:
|
|
704
|
-
```ts
|
|
705
|
-
import { createServer } from "@bractjs/bractjs";
|
|
706
|
-
import lifecycle from "./app/lifecycle.ts";
|
|
707
|
-
createServer({ port: 3000, ...lifecycle });
|
|
708
|
-
```
|
|
709
|
-
|
|
710
|
-
`createServer()` returns `{ stop }`. `stop()` runs `onShutdown` and closes the listener but does **not** call `process.exit()` (good for tests/supervisors). Signals do exit.
|
|
711
|
-
|
|
712
|
-
---
|
|
713
|
-
|
|
714
|
-
## 17. Environment variables
|
|
715
|
-
|
|
716
|
-
| Convention | Behavior |
|
|
717
|
-
|---|---|
|
|
718
|
-
| `*.server.ts` / `*.server.tsx` | **Stubbed out of the client bundle.** Import it freely from a route's `loader`/`action`; every export is replaced by an inert stub in the browser build, so the real source (DB drivers, secrets, `bun:sqlite`) never ships. The stub throws if you accidentally call it on the client. |
|
|
719
|
-
| Keys listed in `clientEnv` | Replaced with string literals in the client bundle. |
|
|
720
|
-
| Any other `process.env.*` | Becomes the literal `"undefined"` in the client bundle. |
|
|
721
|
-
|
|
722
|
-
```ts
|
|
723
|
-
// db.server.ts — never reaches the browser
|
|
724
|
-
import { Database } from "bun:sqlite";
|
|
725
|
-
export const db = new Database(Bun.env.DATABASE_URL!);
|
|
726
|
-
```
|
|
727
|
-
|
|
728
|
-
```ts
|
|
729
|
-
// app/routes/posts.tsx — import the server module inside the loader
|
|
730
|
-
import { db } from "../db.server.ts"; // stubbed in the client bundle
|
|
731
|
-
|
|
732
|
-
export async function loader() {
|
|
733
|
-
return { posts: db.query("SELECT * FROM posts").all() };
|
|
734
|
-
}
|
|
735
|
-
```
|
|
736
|
-
|
|
737
|
-
> BractJS ships the whole route module — `loader` and `action` included — to the client, so a server import is reachable from the client graph. The `serverModuleStubPlugin` (applied automatically by `bractjs dev`/`build`) replaces every `*.server.ts` export with a throwing stub: the import resolves, the loader/action are dead code on the client, and **zero** server source is emitted. The stricter, hard-failing `serverOnlyPlugin` is still exported if you'd rather a server import be a build error.
|
|
738
|
-
|
|
739
|
-
```ts
|
|
740
|
-
// bractjs.config.ts
|
|
741
|
-
export default { clientEnv: ["PUBLIC_API_URL"] };
|
|
742
|
-
```
|
|
743
|
-
|
|
744
|
-
```ts
|
|
745
|
-
// in a client component — only allow-listed keys survive
|
|
746
|
-
fetch(`${process.env.PUBLIC_API_URL}/items`);
|
|
747
|
-
```
|
|
748
|
-
|
|
749
|
-
On the server, read env via `Bun.env.*` directly.
|
|
750
|
-
|
|
751
|
-
---
|
|
752
|
-
|
|
753
|
-
## 18. Typed routes
|
|
754
|
-
|
|
755
|
-
Generate type-safe routing from your route files — one command wires `<Link>`, `useNavigate`, `useParams`, and `useSearchParams` to your actual routes.
|
|
756
|
-
|
|
757
|
-
```sh
|
|
758
|
-
bractjs codegen # ./app → ./app/route-types.gen.ts
|
|
759
|
-
bractjs codegen ./app ./app/types.ts # explicit paths
|
|
760
|
-
```
|
|
761
|
-
|
|
762
|
-
Runs automatically during `bractjs build`. Make sure the generated file is part of your TypeScript program (it is, if your `tsconfig.json` `include`s `app/`). It augments BractJS's `Register` interface, after which the runtime components and hooks become type-safe — **no per-route imports needed**:
|
|
763
|
-
|
|
764
|
-
```tsx
|
|
765
|
-
<Link to="/blog/:id" params={{ id }} /> // ✅ "/blog/:id" autocompletes; params typed
|
|
766
|
-
<Link to="/blgo/:id" params={{ id }} /> // ❌ typo'd route — compile error
|
|
767
|
-
<Link to="/blog/:id" params={{ x: id }} /> // ❌ wrong param key — compile error
|
|
768
|
-
|
|
769
|
-
const navigate = useNavigate();
|
|
770
|
-
navigate("/blog/:id", { params: { id } }); // ✅ same typing as <Link>
|
|
771
|
-
|
|
772
|
-
const { id } = useParams<"/blog/:id">(); // id: string
|
|
773
|
-
```
|
|
774
|
-
|
|
775
|
-
Building the URL yourself (`<Link to={`/blog/${id}`}>`) still type-checks, so adopting codegen never breaks existing links.
|
|
776
|
-
|
|
777
|
-
The generated file also exports types/helpers for typed loaders and explicit URL building:
|
|
778
|
-
|
|
779
|
-
```ts
|
|
780
|
-
import type { TypedLoaderArgs } from "../route-types.gen.ts";
|
|
781
|
-
import { routes } from "../route-types.gen.ts";
|
|
782
|
-
|
|
783
|
-
export async function loader({ params }: TypedLoaderArgs<"/blog/:id">) {
|
|
784
|
-
return db.post.findById(params.id); // params.id: string
|
|
785
|
-
}
|
|
786
|
-
routes["/blog/:id"]({ id: "123" }); // → "/blog/123" (typo'd routes won't compile)
|
|
787
|
-
```
|
|
788
|
-
|
|
789
|
-
**Type a route's search params or context** by augmenting the package interfaces — `SearchParams<T>` / `Context<T>` and `useSearchParams<T>()` pick it up:
|
|
790
|
-
|
|
791
|
-
```ts
|
|
792
|
-
declare module "@bractjs/bractjs" {
|
|
793
|
-
interface RouteSearchParamsMap { "/blog": { page: string; sort: string } }
|
|
794
|
-
interface RouteContextMap { "/admin": { user: { id: string; role: "admin" } } }
|
|
795
|
-
}
|
|
796
|
-
```
|
|
797
|
-
|
|
798
|
-
You can also call `writeRouteTypes(appDir, outPath?)` / `generateRouteTypes(appDir)` programmatically.
|
|
799
|
-
|
|
800
|
-
> **Heads up:** earlier versions documented `useParams<RouteParams<"/blog/:id">>()` and untyped `<Link to={string}>`. The route-literal form (`useParams<"/blog/:id">()`) and typed `<Link>`/`useNavigate` are the current API; the old forms still compile.
|
|
801
|
-
|
|
802
|
-
---
|
|
803
|
-
|
|
804
|
-
## 19. Internationalization utilities
|
|
805
|
-
|
|
806
|
-
BractJS exports **utilities** for locale-prefixed routing. These are helpers you wire up yourself (there is no fully-automatic locale router yet) plus the `useLocale` / `useLocalizedLink` client hooks (§9).
|
|
807
|
-
|
|
808
|
-
```ts
|
|
809
|
-
import { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "@bractjs/bractjs";
|
|
810
|
-
import type { I18nConfig } from "@bractjs/bractjs";
|
|
811
|
-
|
|
812
|
-
const i18n: I18nConfig = { locales: ["en", "fr"], defaultLocale: "en" };
|
|
813
|
-
|
|
814
|
-
// Add /:locale-prefixed variants alongside the originals.
|
|
815
|
-
const localized = wrapRoutesWithLocale(routeFiles, i18n);
|
|
816
|
-
|
|
817
|
-
// Split a locale off a pathname.
|
|
818
|
-
const { locale, strippedPathname } = stripLocale("/fr/about", i18n.locales);
|
|
819
|
-
// → { locale: "fr", strippedPathname: "/about" }
|
|
820
|
-
|
|
821
|
-
// Build a locale-aware data path.
|
|
822
|
-
localizedDataPath("/about", "fr"); // → "/fr/about"
|
|
823
|
-
```
|
|
824
|
-
|
|
825
|
-
On the client, read the active locale and build localized links:
|
|
826
|
-
|
|
827
|
-
```tsx
|
|
828
|
-
const locale = useLocale("en");
|
|
829
|
-
const to = useLocalizedLink("en");
|
|
830
|
-
<Link to={to("/about")} />; // → /en/about
|
|
831
|
-
```
|
|
832
|
-
|
|
833
|
-
---
|
|
834
|
-
|
|
835
|
-
## 20. Image optimization
|
|
836
|
-
|
|
837
|
-
`<Image>` serves responsive, format-converted images through the built-in `/_image` endpoint. Requires [ImageMagick](https://imagemagick.org) (`magick` or `convert`) — without it, originals are served as-is.
|
|
838
|
-
|
|
839
|
-
```tsx
|
|
840
|
-
import { Image } from "@bractjs/bractjs";
|
|
841
|
-
|
|
842
|
-
<Image src="/public/hero.jpg" alt="Hero" width={1200} height={600} />
|
|
843
|
-
|
|
844
|
-
{/* above-the-fold: eager + fetchpriority=high */}
|
|
845
|
-
<Image src="/public/hero.jpg" alt="Hero" width={1200} priority />
|
|
846
|
-
|
|
847
|
-
<Image
|
|
848
|
-
src="/public/photo.jpg" alt="Photo" width={800}
|
|
849
|
-
format="avif" quality={70} fit="contain"
|
|
850
|
-
sizes="(max-width: 640px) 100vw, 50vw"
|
|
851
|
-
/>
|
|
852
|
-
```
|
|
853
|
-
|
|
854
|
-
| Prop | Type | Default | Notes |
|
|
855
|
-
|------|------|---------|-------|
|
|
856
|
-
| `src` | `string` | — | Path under `/public/` (required) |
|
|
857
|
-
| `alt` | `string` | — | Required |
|
|
858
|
-
| `width` / `height` | `number` | — | Intrinsic size |
|
|
859
|
-
| `quality` | `number` | `80` | 1–100 |
|
|
860
|
-
| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | `"webp"` | `ImageFormat` |
|
|
861
|
-
| `fit` | `"cover" \| "contain" \| "fill"` | `"cover"` | `ImageFit` |
|
|
862
|
-
| `priority` | `boolean` | `false` | Disable lazy load, set `fetchpriority=high` |
|
|
863
|
-
| `sizes` | `string` | `"100vw"` | HTML `sizes` |
|
|
864
|
-
|
|
865
|
-
Generates a `srcset` across breakpoints (320→1920px). Optimized images are cached in memory (LRU, 200 slots) and on disk (`.bract-image-cache/`, survives restarts), both served `Cache-Control: immutable`. The endpoint validates widths against an allowlist, caps total pixel area, limits concurrency, and kills runaway transforms (DoS hardening).
|
|
866
|
-
|
|
867
|
-
`ImageProps`, `ImageFormat`, and `ImageFit` are exported types.
|
|
868
|
-
|
|
869
|
-
---
|
|
870
|
-
|
|
871
|
-
## 21. Build & run
|
|
872
|
-
|
|
873
|
-
### CLI
|
|
874
|
-
|
|
875
|
-
| Command | Description |
|
|
876
|
-
|---------|-------------|
|
|
877
|
-
| `bractjs new <name>` | Scaffold a new app into `<name>/`. |
|
|
878
|
-
| `bractjs dev` | Dev server with HMR (port 3000, HMR ws 3001). |
|
|
879
|
-
| `bractjs build` | Dual server + client build with content-hashed output. |
|
|
880
|
-
| `bractjs start` | Serve the production build. |
|
|
881
|
-
| `bractjs codegen [app] [out]` | Generate `route-types.gen.ts`. |
|
|
882
|
-
| `bractjs codegen:registry [app]` | Generate `app/_generated/{routes,actions}.ts`. |
|
|
883
|
-
| `bractjs codegen:manifest [app] [build]` | Snapshot manifest → `app/_generated/manifest.ts`. |
|
|
884
|
-
| `bractjs compile [outfile] [entry]` | Full single-binary pipeline. |
|
|
885
|
-
|
|
886
|
-
The CLI is a thin wrapper — every command delegates to a public function, so you can script the same thing.
|
|
887
|
-
|
|
888
|
-
### Programmatic API
|
|
889
|
-
|
|
890
|
-
**`createDevServer(options?)`** — dev server with HMR.
|
|
891
|
-
```ts
|
|
892
|
-
import { createDevServer } from "@bractjs/bractjs";
|
|
893
|
-
|
|
894
|
-
const dev = await createDevServer({
|
|
895
|
-
port: 3000, // default: config.port ?? 3000
|
|
896
|
-
hmrPort: 3001, // HMR websocket
|
|
897
|
-
config: { appDir: "./app", clientEnv: ["PUBLIC_API_URL"] },
|
|
898
|
-
skipUserConfig: false, // true → don't read bractjs.config.ts
|
|
899
|
-
});
|
|
900
|
-
dev.stop();
|
|
901
|
-
```
|
|
902
|
-
|
|
903
|
-
**`runBuild(config?)`** — production build (accepts only build-relevant fields).
|
|
904
|
-
```ts
|
|
905
|
-
import { runBuild } from "@bractjs/bractjs";
|
|
906
|
-
|
|
907
|
-
await runBuild({
|
|
908
|
-
appDir: "./app",
|
|
909
|
-
buildDir: "./build",
|
|
910
|
-
minify: true,
|
|
911
|
-
sourcemap: "external", // "none" | "linked" | "inline" | "external"
|
|
912
|
-
clientEnv: ["PUBLIC_API_URL"],
|
|
913
|
-
plugins: [], // extra Bun plugins
|
|
914
|
-
});
|
|
915
|
-
```
|
|
916
|
-
|
|
917
|
-
**`loadUserConfig()`** — read `bractjs.config.ts` (or `.js`) from cwd, validated.
|
|
918
|
-
```ts
|
|
919
|
-
import { loadUserConfig } from "@bractjs/bractjs";
|
|
920
|
-
const cfg = await loadUserConfig(); // {} if no file; throws on a malformed shape
|
|
921
|
-
```
|
|
922
|
-
|
|
923
|
-
**`createServer(config?)`** — production HTTP server. Returns `{ stop }`.
|
|
924
|
-
```ts
|
|
925
|
-
import { createServer } from "@bractjs/bractjs";
|
|
926
|
-
import lifecycle from "./app/lifecycle.ts";
|
|
927
|
-
const srv = createServer({ port: 3000, buildDir: "./build", ...lifecycle });
|
|
928
|
-
```
|
|
929
|
-
|
|
930
|
-
**`buildFetchHandler(config)`** — the adapter-agnostic `(Request) => Promise<Response>` core, if you want to mount BractJS inside another server.
|
|
931
|
-
```ts
|
|
932
|
-
import { buildFetchHandler } from "@bractjs/bractjs";
|
|
933
|
-
const handler = buildFetchHandler({ appDir: "./app", manifest });
|
|
934
|
-
Bun.serve({ port: 3000, fetch: handler });
|
|
935
|
-
```
|
|
936
|
-
|
|
937
|
-
`renderRoute(options)` (low-level SSR render) and the `RenderOptions`/`ServerManifest`/`BractJSConfig` types are also exported for advanced embedding.
|
|
938
|
-
|
|
939
|
-
---
|
|
940
|
-
|
|
941
|
-
## 22. Single-binary deployment (`bun build --compile`)
|
|
942
|
-
|
|
943
|
-
BractJS compiles to a single executable. Because `bun build --compile` can't trace runtime fs scans or dynamic `import(absPath)`, a codegen step materializes routes, layouts, actions, and the manifest into static imports so the binary boots with **zero filesystem reads of `appDir`**.
|
|
944
|
-
|
|
945
|
-
### One-shot
|
|
946
|
-
|
|
947
|
-
```sh
|
|
948
|
-
bractjs compile ./myapp
|
|
949
|
-
# = codegen:registry → build → codegen:manifest → bun build --compile app/server.ts
|
|
950
|
-
```
|
|
951
|
-
|
|
952
|
-
### The `app/server.ts` entry
|
|
953
|
-
|
|
954
|
-
The scaffold includes:
|
|
955
|
-
|
|
956
|
-
```ts
|
|
957
|
-
import { createServer } from "@bractjs/bractjs";
|
|
958
|
-
import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
|
|
959
|
-
import { actionModules } from "./_generated/actions.ts";
|
|
960
|
-
import { manifest } from "./_generated/manifest.ts";
|
|
961
|
-
|
|
962
|
-
createServer({
|
|
963
|
-
port: Number(process.env.PORT ?? 3000),
|
|
964
|
-
appDir: "./app",
|
|
965
|
-
publicDir: "./public",
|
|
966
|
-
manifest, // no manifest read from disk
|
|
967
|
-
routeFiles, // no Bun.Glob route scan
|
|
968
|
-
moduleRegistry, // no dynamic import(absPath)
|
|
969
|
-
actionModules, // no scan/import for "use server" files
|
|
970
|
-
});
|
|
971
|
-
```
|
|
972
|
-
|
|
973
|
-
When all four are present, the server uses the pre-imported modules for routing, layouts, actions, and assets.
|
|
974
|
-
|
|
975
|
-
### Manual pipeline
|
|
976
|
-
|
|
977
|
-
```sh
|
|
978
|
-
bractjs codegen:registry # A — scan routes/actions → static imports
|
|
979
|
-
bractjs build # B — client + server bundles + manifest
|
|
980
|
-
bractjs codegen:manifest # C — embed manifest as a TS constant
|
|
981
|
-
bun build --compile app/server.ts \ # D — single binary
|
|
982
|
-
--asset build/client/ --outfile ./myapp
|
|
983
|
-
```
|
|
984
|
-
|
|
985
|
-
`--asset build/client/` embeds JS/CSS into the binary (true single file); omit it to ship `myapp` + `build/client/` side by side.
|
|
986
|
-
|
|
987
|
-
The codegen functions are exported: `writeModuleRegistries(appDir)`, `writeManifestModule(appDir, buildDir)`, and the lower-level `generateRouteRegistry` / `generateActionRegistry` / `generateManifestModule`.
|
|
988
|
-
|
|
989
|
-
> **Contributor note — keep the binary working:** anything on the server request/startup path must avoid runtime `Bun.Glob`/computed-path `import()`, must fall back from `realpath()` to `Bun.file().exists()` for embedded assets, and must preserve every consumed export when projecting route modules. Two tests enforce this: `src/__tests__/compile-safety.test.ts` (fast static scan) and `src/__tests__/compile-smoke.test.ts` (compiles and boots a real binary).
|
|
990
|
-
|
|
991
|
-
---
|
|
992
|
-
|
|
993
|
-
## 23. Custom adapters
|
|
994
|
-
|
|
995
|
-
The server core is adapter-agnostic. The default is `BunAdapter` (wraps `Bun.serve`); supply your own via `createServer({ adapter })`.
|
|
996
|
-
|
|
997
|
-
```ts
|
|
998
|
-
import type { BractAdapter } from "@bractjs/bractjs";
|
|
999
|
-
import { BunAdapter } from "@bractjs/bractjs";
|
|
1000
|
-
|
|
1001
|
-
// BractAdapter: { fetch(req): Promise<Response>; listen?(port): void }
|
|
1002
|
-
```
|
|
1003
|
-
|
|
1004
|
-
**Cloudflare Workers:**
|
|
1005
|
-
```ts
|
|
1006
|
-
import { buildFetchHandler, makeCloudflareHandler } from "@bractjs/bractjs";
|
|
1007
|
-
const handler = buildFetchHandler({ appDir: "./app", manifest });
|
|
1008
|
-
export default makeCloudflareHandler(handler);
|
|
1009
|
-
// or createCloudflareAdapter(handler) for the BractAdapter-compatible form
|
|
1010
|
-
```
|
|
1011
|
-
|
|
1012
|
-
---
|
|
1013
|
-
|
|
1014
|
-
## 24. Build plugins
|
|
1015
|
-
|
|
1016
|
-
If you write your own `Bun.build()` (instead of `bractjs build`), you **must** apply these or face crashes / secret leaks. All are exported.
|
|
1017
|
-
|
|
1018
|
-
| Bundle | Plugin | Without it |
|
|
1019
|
-
|---|---|---|
|
|
1020
|
-
| Server | `useClientStubPlugin` | Server crashes calling browser-only hooks from `"use client"` modules. |
|
|
1021
|
-
| Client | `createUseServerProxyPlugin(appDir)` | Server-action bodies (DB code, secrets) ship in the browser JS. |
|
|
1022
|
-
| Client | `serverModuleStubPlugin` | `*.server.ts` source (DB drivers, secrets) leaks into the client bundle. |
|
|
1023
|
-
| Client | `clientEnvPlugin(allowedKeys, env)` | Server env vars leak into the browser bundle. |
|
|
1024
|
-
| Client | `cssModulesPlugin` | `*.module.css` imports don't resolve. |
|
|
1025
|
-
|
|
1026
|
-
```ts
|
|
1027
|
-
import {
|
|
1028
|
-
useClientStubPlugin, createUseServerProxyPlugin,
|
|
1029
|
-
serverModuleStubPlugin, clientEnvPlugin, cssModulesPlugin,
|
|
1030
|
-
} from "@bractjs/bractjs";
|
|
1031
|
-
|
|
1032
|
-
// Server bundle (target: "bun"):
|
|
1033
|
-
plugins: [useClientStubPlugin];
|
|
1034
|
-
|
|
1035
|
-
// Client bundle (target: "browser"):
|
|
1036
|
-
plugins: [
|
|
1037
|
-
serverModuleStubPlugin,
|
|
1038
|
-
createUseServerProxyPlugin("./app"), // same appDir as createServer!
|
|
1039
|
-
clientEnvPlugin(["PUBLIC_API_URL"], Bun.env as Record<string, string>),
|
|
1040
|
-
cssModulesPlugin,
|
|
1041
|
-
];
|
|
1042
|
-
```
|
|
1043
|
-
|
|
1044
|
-
> Always pass the **same `appDir`** to `createUseServerProxyPlugin` that you pass to `createServer` — action IDs hash the appDir-relative path, so a mismatch makes every `/_action` return 404. `transformCssModule(filePath)` is exported for custom CSS pipelines; `useServerProxyPlugin` is the legacy absolute-path variant. `serverModuleStubPlugin` stubs `*.server.ts` exports so a route can import a server module inside its loader/action without leaking source; `serverOnlyPlugin` is the stricter predecessor that hard-fails such imports instead (still exported for opt-in use).
|
|
1045
|
-
|
|
1046
|
-
---
|
|
1047
|
-
|
|
1048
|
-
## 25. Configuration reference
|
|
1049
|
-
|
|
1050
|
-
All fields optional. Put them in `bractjs.config.ts` (default export) or pass to `createServer` / `createDevServer` / `runBuild`.
|
|
1051
|
-
|
|
1052
|
-
| Field | Type | Default | Description |
|
|
1053
|
-
|-------|------|---------|-------------|
|
|
1054
|
-
| `port` | `number` | `3000` | TCP port |
|
|
1055
|
-
| `appDir` | `string` | `"./app"` | Contains `routes/` and `root.tsx` |
|
|
1056
|
-
| `publicDir` | `string` | `"./public"` | Static assets (served no-cache) |
|
|
1057
|
-
| `buildDir` | `string` | `"./build"` | Build output |
|
|
1058
|
-
| `imageCacheDir` | `string` | `".bract-image-cache"` | Optimized-image disk cache |
|
|
1059
|
-
| `sourcemap` | `string` | `"external"` | `"none" \| "linked" \| "inline" \| "external"` |
|
|
1060
|
-
| `minify` | `boolean` | `true` | Minify client bundles |
|
|
1061
|
-
| `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
|
|
1062
|
-
| `plugins` | `BunPlugin[]` | `[]` | Extra client-build plugins |
|
|
1063
|
-
| `adapter` | `BractAdapter` | `BunAdapter` | Custom server adapter |
|
|
1064
|
-
| `i18n` | `I18nConfig` | — | Locale config consumed by the i18n utilities |
|
|
1065
|
-
| `onStart` / `onShutdown` / `onError` | hooks | — | Lifecycle (§16) |
|
|
1066
|
-
|
|
1067
|
-
`loadUserConfig()` validates these shapes and throws a clear error on an obvious mistake (e.g. a string `port`).
|
|
1068
|
-
|
|
1069
|
-
---
|
|
1070
|
-
|
|
1071
|
-
## 26. Full export index
|
|
1072
|
-
|
|
1073
|
-
Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
|
|
1074
|
-
|
|
1075
|
-
**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `BunAdapter`, `defineLifecycle`
|
|
1076
|
-
|
|
1077
|
-
**Errors:** `BractJSError`, `HttpError`, `isRedirect`, `isHttpError`, `isBractJSError`
|
|
1078
|
-
|
|
1079
|
-
**Streaming:** `defer`, `Deferred`, `isDeferred`, `Await`
|
|
1080
|
-
|
|
1081
|
-
**Context:** `BractJSContext`, `BractJSProvider`, `useBractJSContext`
|
|
1082
|
-
|
|
1083
|
-
**Middleware:** `pipeline`, `MiddlewarePipeline`, `requestLogger`, `cors`, `authGuard`, `csp`, `getCspNonce`, `CSP_NONCE_KEY`
|
|
1084
|
-
|
|
1085
|
-
**Sessions:** `createCookieSession`
|
|
1086
|
-
|
|
1087
|
-
**Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`
|
|
1088
|
-
|
|
1089
|
-
**Hooks:** `useLoaderData`, `useActionData`, `useParams`, `useNavigation`, `useFetcher`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
|
|
1090
|
-
|
|
1091
|
-
**i18n:** `wrapRoutesWithLocale`, `stripLocale`, `localizedDataPath`
|
|
1092
|
-
|
|
1093
|
-
**Client RPC:** `createClient`
|
|
1094
|
-
|
|
1095
|
-
**Build / programmatic:** `createDevServer`, `runBuild`, `loadUserConfig`
|
|
1096
|
-
|
|
1097
|
-
**Codegen:** `writeModuleRegistries`, `writeManifestModule`, `generateRouteRegistry`, `generateActionRegistry`, `generateManifestModule`
|
|
1098
|
-
|
|
1099
|
-
**Build plugins:** `useClientStubPlugin`, `createUseServerProxyPlugin`, `useServerProxyPlugin`, `serverModuleStubPlugin`, `serverOnlyPlugin`, `clientEnvPlugin`, `cssModulesPlugin`, `transformCssModule`
|
|
1100
|
-
|
|
1101
|
-
**Adapters:** `createCloudflareAdapter`, `makeCloudflareHandler`
|
|
1102
|
-
|
|
1103
|
-
**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `BractJSConfig`, `RenderOptions`, `ServerManifest`, `ContextFactory`, `ApiRouteDefinition`, `AppApiRoutes`, `FieldErrors`, `ValidationError`, `BractAdapter`, `LifecycleHooks`, `MiddlewareFn`, `MiddlewareContext`, `CorsOptions`, `AuthGuardOptions`, `CspOptions`, `SessionStorageLike`, `SessionLike`, `Session`, `SessionStorage`, `SessionData`, `CookieSessionOptions`, `CommitOptions`, `ImageProps`, `ImageFormat`, `ImageFit`, `SearchParamsResult`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
|
|
1104
|
-
|
|
1105
|
-
---
|
|
1106
|
-
|
|
1107
|
-
## Changelog
|
|
1108
|
-
|
|
1109
|
-
See [CHANGELOG.md](CHANGELOG.md) for release history.
|
|
1110
|
-
|
|
1111
|
-
---
|
|
1112
|
-
|
|
1113
|
-
## Why BractJS
|
|
1114
|
-
|
|
1115
|
-
- **Bun-native** — `Bun.serve`, `Bun.build`, `Bun.file`, `Bun.Glob`, `Bun.watch`. No Node.js.
|
|
1116
|
-
- **Zero framework deps** — only peers are `react` and `react-dom`.
|
|
1117
|
-
- **Streaming SSR** — `renderToReadableStream()` with `defer()` and `<Await>`.
|
|
1118
|
-
- **File-based routing** — drop a file in `app/routes/`.
|
|
1119
|
-
- **Full-stack** — loaders, actions, sessions, server actions, typed API routes, middleware.
|
|
1120
|
-
- **Typed routes** — codegen wires `<Link>`, `useNavigate`, and `useParams` to your routes (autocompleted paths, typed params), plus a type-safe URL builder.
|
|
1121
|
-
- **Single-binary** — `bun build --compile` to one executable.
|
|
1122
|
-
|
|
1123
|
-
## License
|
|
1124
|
-
|
|
1125
|
-
MIT
|