@k8ordo/framework 0.1.0 → 1.1.0

package/docs/references/deploy.md

@@ -465,8 +465,8 @@ on evil.test would pass the check.
 
 ```ts
 // vite.config.ts
-import { framework } from '@k8ordo/framework/vite';
 import { vercel } from '@k8ordo/framework/vercel';
+import { framework } from '@k8ordo/framework/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
@@ -505,6 +505,163 @@ case-sensitively, as the route table matches; then `404.html` under a `404`,
 when the build wrote one. `vercel()` writes them once the last page is
 written, whichever side of `framework()` it sits.
 
+**A file a `route.ts` wrote is served with the type its `GET` answered**,
+the `Content-Type` `vite dev` sends, written as that file's entry in the
+`overrides` of `config.json`: a feed at `blog/feed` is
+`application/rss+xml`, not the `application/octet-stream` of a file with no
+extension. The type is written even where the extension says the same, so
+no file is left to the type Vercel gives an extension; only a `GET` that
+named none — a body of bytes with no `Content-Type` — leaves its file to it.
+`vite preview` and `serve` still go by the extension
+([A route.ts under static mode](routing.md#under-static-mode)).
+
+### Routes of your own
+
+Under `mode: 'static'`, `vercel()` also takes routes of the application's
+own, in the language Vercel's Build Output API reads — `src`, a regular
+expression for the pathname, with `dest`, `status`, `headers`, `continue`,
+`check`, `caseSensitive` and `has` — and writes them into
+`.vercel/output/config.json` as given, in two places among its own:
+
+```text
+...beforeFiles
+{ handle: 'filesystem' }        the files
+...the shells' rewrites
+...beforeNotFound
+404.html under a 404            when the build wrote one
+{ handle: 'hit' }
+assets/ sent immutable
+```
+
+`beforeFiles` is tried before any file, so it is where headers for every
+answer go, and a redirect or a rewrite that has to win over a file that is
+there. `beforeNotFound` is tried once neither a file nor a shell answered,
+so a catch-all of yours there never hides a shell: it is where a URL the
+build wrote nothing for is proxied to another origin, or answered with a 404
+of another body.
+
+```ts
+// vite.config.ts
+import { vercel } from '@k8ordo/framework/vercel';
+import { framework } from '@k8ordo/framework/vite';
+import { defineConfig } from 'vite';
+
+const acceptsMarkdown = [
+  { type: 'header', key: 'accept', value: '.*text/markdown.*' },
+] as const;
+
+export default defineConfig({
+  plugins: [
+    framework({ mode: 'static' }),
+    vercel({
+      beforeFiles: [
+        {
+          src: '^/.*$',
+          headers: { 'X-Content-Type-Options': 'nosniff' },
+          continue: true,
+        },
+        {
+          src: '^/((?:[^/]+/)*[^/]+)/$',
+          status: 308,
+          headers: { Location: '/$1' },
+        },
+        {
+          src: '^/posts/([a-z0-9-]+)$',
+          has: acceptsMarkdown,
+          dest: '/posts/$1/article.md',
+          check: true,
+          caseSensitive: true,
+        },
+        {
+          src: '^/feed$',
+          headers: { 'Vercel-CDN-Cache-Control': 'max-age=3600' },
+          continue: true,
+          caseSensitive: true,
+        },
+      ],
+      beforeNotFound: [
+        {
+          src: '^/feed$',
+          dest: 'https://api.example.com/feed',
+          caseSensitive: true,
+        },
+        {
+          src: '^/.*$',
+          has: acceptsMarkdown,
+          dest: '/not-found.md',
+          status: 404,
+        },
+      ],
+    }),
+  ],
+});
+```
+
+- A route that only adds headers says `continue: true`, and comes before
+  the route that answers: an answering route ends the matching. What
+  `beforeFiles` adds this way is on every answer the routes lead to — a
+  file, a redirect, `404.html`, a `dest` with a `status`, an answer proxied
+  from another origin.
+- The redirect takes the trailing slash off and keeps the query:
+  `/about/?x=1` goes to `/about?x=1`, which Vercel answers from
+  `about/index.html` as it is. Its pattern takes no empty segment, so it
+  never answers with `Location: //evil.test`, which a browser reads as
+  another origin. Vercel itself answers `//evil.test/` before any route, with
+  a 308 to `/evil.test/` that carries none of your headers.
+- `check: true` looks for `dest` among the files. When none is there, the
+  matching goes on with `dest` as the pathname: `beforeNotFound` sees
+  `/posts/nope/article.md`, not `/posts/nope`. Here a `route.ts` at
+  `routes/posts/[slug]/article.md/` wrote each post's markdown beside its
+  page, and a client asking for markdown is answered with it. Have `paths`
+  give the pages and their markdown from one list of posts, so no post is
+  written without the other.
+- `has` matches the header's text against `value`, a regular expression,
+  and negotiates nothing: `.*text/markdown.*` takes
+  `Accept: text/markdown, text/html;q=0.9`, and not a browser's
+  `text/html,application/xhtml+xml,*/*;q=0.8`, though `*/*` would take
+  markdown.
+- A proxy is two routes: its headers ahead of the files, and the `dest` that
+  answers after them. The `dest` is asked with the request's query:
+  `/feed?page=2` fetches `https://api.example.com/feed?page=2`.
+- `dest` with `status` answers with that file under that status, as the
+  build's own `404.html` route does.
+
+What to keep in mind:
+
+- **`src` matches the whole pathname**, never just its start, and never the
+  query: `^/posts/` does not match `/posts/first`, and `^/posts/.+$` does.
+- **Only Vercel applies them.** `vite dev`, `vite preview` and `serve`
+  answer as if they were not there — no header, no redirect, nothing decided
+  by `Accept` — since an imitation of Vercel's routing that differed from it
+  would pass locally and fail once deployed. A URL only a route of yours
+  answers is a 404 there.
+- **No `Cache-Control` in a route every path takes.** It reaches every file
+  too, those under `assets/` among them, which `vercel()` marks `immutable`
+  in the `hit` phase, after yours. Give a `Cache-Control` a `src` that names
+  the paths it is for.
+- **Vercel matches `src` regardless of case** unless the route says
+  `caseSensitive: true`, while the routes `vercel()` writes itself are
+  case-sensitive, as the route table is. A route without it answers
+  `/POSTS/first` as well.
+- **`has` names a header in lowercase**, as Vercel compares it. `vercel()`
+  refuses another spelling when it is called:
+
+  ```text
+  vercel() route ^/posts/([a-z0-9-]+)$ has the header key "Accept" — write it lowercase ("accept"), as Vercel compares it
+  ```
+
+- **Nothing else is checked.** The routes are written as given — under a
+  `base` their `src` and `dest` carry it — and their patterns are Vercel's
+  (PCRE), which JavaScript's `RegExp` would misjudge, so a mistake shows once
+  deployed. Try a change on a preview deployment first.
+- **Static mode only.** Under `mode: 'server'` the request handler answers
+  every URL no file names, and a `guard.ts` or a `route.ts` decides what it
+  sends. The build refuses them there:
+
+  ```text
+  vercel() takes beforeFiles and beforeNotFound under mode: 'static' only — under mode: 'server' the handler answers every URL no file names
+  ```
+
 ## A tab opened before a deploy
 
 A tab keeps running the script it loaded, while every payload it fetches

package/docs/references/routing.md

@@ -280,10 +280,14 @@ with params needs `paths`, as a page's does
 ([Parameters](params.md#routes-with-parameters)) — with a request whose
 origin is `site` when that option is given (an RSS feed's links are
 absolute), and writes what it answered as the file at that pathname:
-`dist/client/feed.xml`. A static host then serves it with the type its
-extension says. The `GET` has to answer `200`; anything else stops the build
-naming the pathname. A file answers nothing but `GET`, so a `route.ts`
-exporting another method is refused by name, in the build and in `vite dev`:
+`dist/client/feed.xml`. A file keeps no type of its own, so a static host
+serves it with the type its extension says — `vite preview` and `serve` too,
+which send a file with no extension as `application/octet-stream`. On
+Vercel, `vercel()` serves it with the `Content-Type` its `GET` answered, the
+type `vite dev` sends ([Deploying to Vercel](deploy.md#deploying-to-vercel)).
+The `GET` has to answer `200`; anything else stops the build naming the
+pathname. A file answers nothing but `GET`, so a `route.ts` exporting
+another method is refused by name, in the build and in `vite dev`:
 
 ```
 static build writes a route.ts as the file its GET answers, and a file cannot answer another method — these export one:
@@ -299,6 +303,11 @@ A `route.ts` at `/` cannot be a file (the host serves `/` from `index.html`),
 nor one with pages written below it, which would need a directory of the same
 name. What it writes is not a page, so `sitemap.xml` leaves it out.
 
+Name the type in the `Response`. A string body with none is sent as
+`text/plain;charset=UTF-8` — the `Response` sets it — so a `sitemap.xml`
+returned that way is plain text on Vercel and in `vite dev`, whatever its
+extension says. `vite dev` shows it before a deploy does.
+
 ## The generated files
 
 The framework writes `.k8ordo/` and keeps it in step with the directories.
@@ -311,10 +320,10 @@ import { defineRoutes } from '@k8ordo/framework/generated';
 import type { ParamsOf, ParsedParams } from '@k8ordo/framework/generated';
 import type { ComponentType, ReactNode } from 'react';
 
+import layout from '../src/routes/layout';
 import page from '../src/routes/page';
-import products_page from '../src/routes/products/page';
 import products_id_page from '../src/routes/products/[id]/page';
-import layout from '../src/routes/layout';
+import products_page from '../src/routes/products/page';
 
 type Page<P extends string, S extends readonly unknown[] = []> = ComponentType<{
   params: ParsedParams<P, S>;
@@ -384,6 +393,35 @@ import { href } from '@k8ordo/framework';
 <a href={href('/products/:id', { id })}>…</a>; // checked against routes/
 ```
 
+It registers the locale set with `@k8ordo/i18n` too, when the application
+has one: its `package.json` lists `@k8ordo/i18n` (in `dependencies` or
+`devDependencies`), and `src/i18n.ts` exports the set as `locales`. That is
+the `Register` an application outside the framework writes by hand, so here
+it writes none, and a message missing a locale does not compile:
+
+```ts
+// .k8ordo/register.gen.ts (the part for @k8ordo/i18n)
+import type { LocaleOf } from '@k8ordo/i18n';
+
+import type { locales } from '../src/i18n';
+
+declare module '@k8ordo/i18n' {
+  interface Register {
+    locale: LocaleOf<typeof locales>;
+  }
+}
+```
+
+The export is read from the file's syntax, as a route file's are, and never
+by running it: `export const locales = defineLocales(…)` and
+`export { locales } from './locales'` count, a type-only export and
+`export *` do not. A `src/i18n.ts` without the export gets nothing
+generated and a warning naming it, since every message would compile
+unchecked; an application that keeps its set elsewhere writes the
+`Register` by hand. `vite dev` writes the file again as `src/i18n.ts` comes,
+goes, or gains or loses the export. A hand-written augmentation left in the
+application still compiles beside it, since both declare the same type.
+
 Neither file names `@k8ordo/router`: they import from
 `@k8ordo/framework/generated`, so the application's code, generated or not,
 reads only the framework.
@@ -397,7 +435,8 @@ vite build && tsc --noEmit
 ```
 
 Without the files, `tsc` checks against no table: `href` takes any string,
-params typed by a `paramsSchema` are strings, and under `mode: 'server'` the
+params typed by a `paramsSchema` are strings, a message missing a locale
+compiles, and under `mode: 'server'` the
 `request` and `search` props are not in `PageProps` or `LayoutProps`, so a
 page that reads them fails with `Property 'request' does not exist`. That is
 the error static mode gives on purpose, but here the mode is not the cause.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/framework",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "The k8ordo framework: routes/ compiled into React Server Components, run with or without a server.",
   "keywords": [
     "k8ordo",
@@ -61,8 +61,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@vitejs/plugin-react": "6.1.1",
-    "@vitejs/plugin-rsc": "0.5.35",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitejs/plugin-rsc": "0.5.38",
     "compressible": "2.0.18",
     "fresh": "2.0.0",
     "mime-types": "3.0.2",
@@ -73,26 +73,33 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
     "@k8ordo/framework-engine": "^0.1.1",
-    "@k8ordo/router": "^1.0.0",
+    "@k8ordo/router": "^1.1.0",
     "@types/compressible": "2.0.3",
     "@types/fresh": "0.5.3",
     "@types/mime-types": "3.0.1",
     "@types/range-parser": "1.2.7",
     "@types/react": "19.3.0",
-    "publint": "0.3.24",
-    "react": "19.3.0",
-    "react-dom": "19.3.0",
+    "oxc-transform-react": "0.154.0",
+    "publint": "0.3.25",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
-    "vite-plus": "0.3.2",
-    "vitest": "5.0.2"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0",
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "@k8ordo/router": "^1.0.0",
+    "@k8ordo/router": "^1.1.0",
+    "oxc-transform-react": "^0.152.0",
     "react": ">=19.3.0",
     "react-dom": ">=19.3.0",
     "vite": ">=8.0.0"
   },
+  "peerDependenciesMeta": {
+    "oxc-transform-react": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24.0.0"
   },