@orieljs/framework 0.1.0-alpha.10 → 0.1.0-alpha.11

package/dist/jsx-runtime.js

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-VOYW3R5J.js";
-import "./chunk-7ZQZYDOC.js";
-import "./chunk-GVNLZZTN.js";
+} from "./chunk-24673JQF.js";
+import "./chunk-MURTCTRH.js";
+import "./chunk-HTJKT2R2.js";
 export {
   Fragment,
   jsx,

package/dist/testing.js

@@ -52,9 +52,9 @@ import {
   travelBack,
   travelTo,
   usingInMemoryDatabase
-} from "./chunk-OXAATQA6.js";
-import "./chunk-7ZQZYDOC.js";
-import "./chunk-GVNLZZTN.js";
+} from "./chunk-KDE5BLI3.js";
+import "./chunk-MURTCTRH.js";
+import "./chunk-HTJKT2R2.js";
 export {
   AnonymousNotifiable,
   AssertableInertia,

package/docs/console.md

@@ -55,6 +55,7 @@ These are the commands every app has. A new app adds one of its own, `inspire`,
 | Command | What it does |
 | --- | --- |
 | `about` | Shows your app's name, the Oriel and Node versions, the environment, debug mode and URL |
+| `export` | Saves your app's pages as files any static host serves ([Static export](export.md)) |
 | `help` | Shows a command's help screen |
 | `list` | Lists the commands, all of them or one group's |
 | `serve` | Serves your app on Oriel's server; `--watch` restarts it when your code changes |
@@ -115,6 +116,7 @@ These are the commands every app has. A new app adds one of its own, `inspire`,
 | `schedule:run` | Runs the scheduled tasks that are due |
 | `schedule:work` | Runs the tasks that are due, every minute, until you stop it |
 | `storage:link` | Links `public/storage` to `storage/app/public` |
+| `vercel:build` | Writes your app's build for Vercel into `.vercel/output` ([Deploying to Vercel](deployment.md#deploying-to-vercel)) |
 
 `node oriel help <command>` lists a command's options. A few that are worth knowing up front:
 

package/docs/deployment.md

@@ -10,6 +10,10 @@ So deploying it means starting that process, keeping it running, and restarting
 the processes beside it: the queue workers, the scheduler and, for the Inertia kits with server-side rendering, the
 SSR server.
 
+An app whose pages are the same for every visitor can skip the server altogether: [Static export](export.md) saves its
+pages as files any static host serves. On Vercel, your app runs without a server of its own, in a function that starts
+when requests come: see [Deploying to Vercel](#deploying-to-vercel).
+
 ## Server requirements
 
 Your server needs **Node 22** or later, or **Bun 1.2** or later. On Node, your app's TypeScript runs through `tsx`,
@@ -238,6 +242,97 @@ node oriel inertia:stop-ssr
 
 Laravel's `reload` command, which does both, isn't in Oriel.
 
+## Deploying to Vercel
+
+On Vercel there is no server to keep running: Vercel's CDN sends the files in `public`, and every other request goes
+to a function that runs your app. `node oriel vercel:build` writes both into `.vercel/output`, the folder Vercel
+deploys (its [Build Output API](https://vercel.com/docs/build-output-api)): `static` holds `public`, whose built
+assets are cached for a year as `serve()` sends them, and the function holds your app's code,
+`public/build/manifest.json` and your production dependencies. Your `.env` files and your
+SQLite databases are left out: the secrets come from Vercel's environment variables, and the database from a server.
+
+### Setting up the project
+
+Add a `vercel.json` to your app, so that Vercel's build runs the command:
+
+```json title="vercel.json"
+{
+  "framework": null,
+  "buildCommand": "npm run build && node oriel migrate --force && node oriel vercel:build"
+}
+```
+
+The API kit has no `build` script: leave `npm run build &&` out. Then import your repository in Vercel, or deploy from
+your machine with `npx vercel deploy`: either way, the build runs on Vercel's machines, which run Linux, as its
+functions do. The function holds native packages built for the machine that ran the build, such as esbuild, which
+`tsx` needs, so a function built on macOS or Windows fails on Vercel. `vercel:build` warns when it runs elsewhere than
+Linux: don't deploy that build with `vercel deploy --prebuilt`.
+
+`migrate --force` runs on every deploy, the previews' too. Give the Preview environment a database of its own, such as
+a branch of your production database, so that a preview never migrates your live data.
+
+### Environment variables
+
+Set your app's values in the project's settings, under Environment Variables:
+
+```dotenv
+APP_ENV=production
+APP_DEBUG=false
+APP_KEY=base64:...
+APP_URL=https://example.vercel.app
+DB_CONNECTION=pgsql
+DB_URL=postgres://...
+SESSION_DRIVER=database
+CACHE_STORE=database
+QUEUE_CONNECTION=sync
+INERTIA_SSR_ENABLED=false
+```
+
+Vercel gives them to the build, which runs the migrations, and to the function. PostgreSQL needs `pg` in your
+dependencies (`npm install pg`); Vercel's Marketplace has PostgreSQL databases with a free plan, which set `DB_URL`'s
+value for you under a name of their own, such as `DATABASE_URL`: copy it into `DB_URL`. When the address says
+`sslmode=require`, as Neon's do, `pg` warns on every cold start: write `sslmode=verify-full`, which also checks the
+server's certificate.
+
+### What changes on Vercel
+
+Vercel starts an instance of the function when requests come, and stops it when they stop. The first request to a new
+instance boots your app; the next ones reuse it. Nothing your app keeps in memory or on disk outlasts the instance,
+and each instance has its own, so:
+
+- **Your database is a server**, PostgreSQL or MySQL. The function's files are read-only, so SQLite can't write.
+- **Sessions and the cache** need a store every instance shares: `database` (the kits have the `sessions` and `cache`
+  tables' migrations) or `redis`. Sessions can also use `cookie`. `file` and `array` don't outlast the instance.
+- **Logs** go to stderr, which Vercel's logs show: the function sets `LOG_CHANNEL=stderr` when you don't set it.
+- **Vercel's proxy is trusted.** Every request reaches the function through it, and it sets the `X-Forwarded-*`
+  headers itself, so the function trusts them when `trusted_proxies`, in `config/http.ts`, is empty: your URLs keep
+  the browser's `https`, and `request().ip()` is the visitor's (see
+  [Configuring trusted proxies](requests.md#configuring-trusted-proxies)).
+- **Files your app stores** go on an `s3` disk (see [File storage](storage.md)): the `local` and `public` disks write
+  into `storage`, which the function can't.
+- **No queue worker or scheduler runs.** With `QUEUE_CONNECTION=sync`, a job runs during the request that dispatches
+  it.
+- **Inertia pages render in the browser**, as they do when no SSR server answers: the SSR server doesn't run on
+  Vercel. `INERTIA_SSR_ENABLED=false` skips asking it.
+
+### Caching pages on the CDN
+
+Pages that are the same for every visitor can be kept by Vercel's CDN, so that most requests for them never reach the
+function. The `cache.headers` middleware sets their `Cache-Control`: `s_maxage` is how many seconds the CDN keeps a
+page, and `stale_while_revalidate` how long it may still send the old copy while it fetches a new one:
+
+```ts title="routes/web.ts"
+import { Route, StartSession, VerifyCsrfToken, view } from '@orieljs/framework'
+
+Route.get('/pricing', () => view('pricing'))
+  .middleware('cache.headers:public;s_maxage=3600;stale_while_revalidate=60')
+  .withoutMiddleware(StartSession, VerifyCsrfToken)
+```
+
+`cache.headers` leaves a response that sets a cookie alone, so that the CDN never hands one visitor's cookies to the
+next. The `web` group's `StartSession` and `VerifyCsrfToken` set cookies on every page: take them off the pages you
+cache, as above. Those pages have no session, so they can't show who is signed in.
+
 ## Debug mode
 
 `debug` in `config/app.ts` reads `APP_DEBUG`, and decides how much an error response shows (see

package/docs/export.md

@@ -0,0 +1,93 @@
+# Static export
+
+When every visitor sees the same pages, `oriel export` saves your app's pages as plain files that any static host can
+serve, with no Oriel server running.
+
+## Introduction
+
+A documentation site, a blog without comments, a product page: some apps answer every visitor the same way. For them,
+running a server is optional. `oriel export` starts your app, asks it for each page the way a browser would, and writes
+the answers to a folder. Upload the folder to any static host, such as Vercel, Netlify, GitHub Pages or an S3 bucket,
+and the site works without a server.
+
+The pages are still made by your app: its routes, controllers, views and middleware all run, once per page, while you
+export. What an export can't keep is anything that happens per request: forms that post, sessions, logins, Live
+components and anything else that needs the server to answer.
+
+## Exporting your app
+
+Build the assets first, then export:
+
+```sh
+npm run build
+node oriel export
+```
+
+The site is written to `dist/`. The command lists the redirects it met and how many pages it wrote:
+
+```text
+Redirect /old → /about, not written.
+Exported 24 pages to [dist] in 840 ms.
+```
+
+`--output` writes somewhere else:
+
+```sh
+node oriel export --output=site
+```
+
+The export only replaces a folder it made itself (or an empty one), so pointing `--output` at a folder that holds
+other files stops it without deleting anything. It also stops while the Vite dev server runs (`public/hot` exists),
+since the pages would point at the dev server: stop `npm run dev`, build, then export.
+
+## Which pages are exported
+
+The export starts at `/` and follows every link to the same site, using the origin of `app.url`. A link to another
+site, a `mailto:` or `tel:` link, or a link to a file in `public/` is left alone. Query strings and `#anchors` are
+ignored, so `/docs/routing?tab=1#named` exports `/docs/routing`.
+
+Pages nothing links to, such as a feed, are listed in `paths`. Pages to leave out are listed in `exclude`, where `*`
+matches anything. A redirect is listed in the command's output and not written; its target is exported when something
+links to it.
+
+A page that answers with an error (4xx or 5xx) stops the export and names the page. The site is written into a
+temporary folder first, so the last export stays as it was.
+
+## Configuration
+
+Add a `config/export.ts` file to change the defaults:
+
+```ts
+export default {
+  output: 'dist',
+  crawl: true,
+  paths: ['/feed.xml'],
+  exclude: ['/drafts/*'],
+  file_names: 'html',
+}
+```
+
+| Key | Default | |
+| --- | --- | --- |
+| `output` | `'dist'` | The folder the site is written to, relative to the app |
+| `crawl` | `true` | Follow links from `/` and from `paths`; `false` exports only those |
+| `paths` | `[]` | Pages to export besides `/` |
+| `exclude` | `[]` | Pages to leave out; `*` matches anything |
+| `file_names` | `'html'` | `'html'` writes `/docs/routing` as `docs/routing.html`; `'directory'` writes `docs/routing/index.html` |
+
+A path with an extension, such as `/feed.xml`, keeps its name in either style. The files in `public/`, your built
+assets among them, are copied into the folder first.
+
+## The 404 page
+
+When your app has a 404 page (`resources/views/errors/404.tsx`), the export writes it as `404.html`. Vercel, Netlify
+and GitHub Pages show that file for an address that doesn't exist.
+
+## Hosting the files
+
+- **Vercel and Netlify** serve `docs/routing.html` at `/docs/routing` when clean URLs are on (Vercel's `cleanUrls`,
+  Netlify's pretty URLs).
+- **GitHub Pages** and most other hosts serve `docs/routing.html` at `/docs/routing.html`, and
+  `docs/routing/index.html` at `/docs/routing/`: export with `file_names: 'directory'` for addresses without `.html`.
+
+To run your app live instead, with forms, sessions and Live components, see [Deployment](deployment.md).

package/docs/installation.md

@@ -197,6 +197,16 @@ node oriel migrate
 
 For MySQL, `DB_CONNECTION` is `mysql` and the port is usually 3306.
 
+## Editor support
+
+The OrielJS extension for VS Code covers the strings Oriel reads at run time, where TypeScript can't help: it completes
+validation rules, `config()` keys, `env()` names, view names, and the actions and properties in Live's `o:` attributes,
+shows their docs when you hover, and warns about one your app doesn't have. It also runs `route:types` and
+`inertia:types` again when your routes, controllers or pages change, and puts the `oriel` commands in the command
+palette. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=orieljs.orieljs),
+or search for OrielJS in the editor's Extensions view. It needs Oriel 0.1.0-alpha.9 or later, and reads your app only
+in a trusted workspace.
+
 ## Next steps
 
 Read how an app is laid out in [Directory structure](structure.md), and how it reads its settings in

package/docs/middleware.md

@@ -231,6 +231,7 @@ they own.
 | Alias | Middleware | What it does |
 | --- | --- | --- |
 | `auth` | `Authenticate` | Lets signed-in users through. A guest gets a 401 for JSON, or a redirect to the login page. `auth:token` names the guard; with several, the first that has a user wins |
+| `cache.headers` | `SetCacheHeaders` | Sets `Cache-Control` on GET and HEAD responses, as `cache.headers:public;max_age=3600;s_maxage=86400;etag` (`etag` adds an ETag and answers 304 when it matches); a response that sets a cookie is left alone, so a CDN never stores one visitor's page |
 | `can` | `Authorize` | Checks an ability with the gate, as `can:update,post`; a parameter that names a route parameter passes the bound model. A denial is a 403 |
 | `guest` | `RedirectIfAuthenticated` | Lets guests through, and redirects signed-in users |
 | `inertia.encrypt` | `EncryptHistory` | Encrypts the browser history state of the Inertia pages behind it |

package/docs/navigation.json

@@ -22,6 +22,10 @@
         {
           "slug": "deployment",
           "title": "Deployment"
+        },
+        {
+          "slug": "export",
+          "title": "Static export"
         }
       ]
     },

package/docs/starter-kits.md

@@ -194,6 +194,9 @@ And the component classes the pages are built from:
 
 Utilities still override them: `<button class="btn btn-sm w-full">`.
 
+In a production build, these names and Tailwind's are scrambled into short ones: every kit's `vite.config.ts` sets
+`obfuscate: true` (see [Class name scrambling](vite.md#class-name-scrambling)).
+
 ### Accessibility
 
 The kits are built to be read by everyone:

package/docs/vite.md

@@ -163,6 +163,84 @@ Give your CSS file to `input`, or import it from a script, and Vite processes it
 built with Tailwind CSS, through `@tailwindcss/vite`. Vite's own CSS features, such as PostCSS and CSS modules, work as
 its documentation describes.
 
+## Class name scrambling
+
+A production build can give your classes short, meaningless names: `items-center` becomes something like `k3vq` in the
+built CSS, in your scripts, and in the HTML Oriel sends, so your pages give nothing away about how they are styled.
+Every starter kit turns it on; `npm run dev` and your tests keep the names you wrote.
+
+```ts title="vite.config.ts"
+import { oriel } from '@orieljs/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [oriel({ input: ['resources/css/app.css', 'resources/js/app.ts'], obfuscate: true })],
+})
+```
+
+`npm run build` writes the names it chose to `bootstrap/cache/classes.json`, out of `public/`, where anyone could
+download them and read your class names back. The SSR build reads them, so it runs after the client build, as the
+kits' `build` script does. Oriel reads them too, and renames the classes in every HTML page it sends: your views,
+Inertia's server-rendered pages, and Live's components and their updates, with Live's `o:loading-class` and
+`o:offline-class`. Deploy `bootstrap/cache/classes.json` with your built assets. While `npm run dev` runs
+(`public/hot` exists), and while your tests run, Oriel renames nothing.
+
+A class keeps the same short name from one build to the next, so a script that didn't change keeps its contents and
+its file name, and the browser's cached copy stays right.
+
+### What gets renamed
+
+In your scripts, the names in class positions: `class` and `className` props, properties named like `activeClass`,
+`swatchClass` or `iconClasses`, `classList.add()` and its kin, `clsx()`, `cn()` and `classNames()`,
+`el.className = …`, `setAttribute('class', …)`, the selectors you give `querySelector()`, `querySelectorAll()`,
+`closest()` and `matches()`, and each framework's own forms: Vue's `:class`, Svelte's `class:` directives, Solid's
+`classList`, Angular's `[class.name]`. A string anywhere else keeps its words, so `type: 'hidden'` is still a hidden
+input, and a name your CSS doesn't define keeps its name.
+
+Your dependencies keep their class names, and so do the classes their style sheets define, so a library's markup
+always matches its CSS, whether you import it or the library injects it. CSS modules' names are hashed already, and
+stay as Vite wrote them. `dark` is never renamed: the kits' appearance script sets it before the page draws.
+
+### Names built from pieces
+
+A class built from pieces at run time can't be renamed: `` `btn-${variant}` `` asks for `btn-primary`, which the
+built CSS calls something else. The build lists each one it finds, with its file and line:
+
+```text
+These class names are built from pieces, so they aren't scrambled:
+  resources/js/components/Button.tsx:12: `btn-${variant}` builds a class name from pieces, so it keeps its name; …
+```
+
+Write the whole name in a class position instead:
+
+```ts
+declare const button: { className: string }
+declare const variant: 'primary' | 'danger'
+// ---cut---
+button.className = variant === 'danger' ? 'btn btn-danger' : 'btn btn-primary'
+
+const variants = {
+  primary: { label: 'Save', buttonClass: 'btn btn-primary' },
+  danger: { label: 'Delete', buttonClass: 'btn btn-danger' },
+}
+```
+
+Or keep those names as they are, with `keep`:
+
+```ts
+import { oriel } from '@orieljs/vite'
+// ---cut---
+oriel({ input: ['resources/css/app.css', 'resources/js/app.ts'], obfuscate: { keep: ['btn-primary', 'btn-danger'] } })
+```
+
+`keep` is also for a class something outside the build looks for, such as a script on another site or a test that
+reads a production page.
+
+### Turning it off
+
+`obfuscate: false`, or no `obfuscate` at all, which is the default: the build keeps your class names, removes an
+earlier build's `classes.json`, and Oriel sends your HTML as it is.
+
 ## Working with views and routes
 
 ### Processing static assets with Vite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orieljs/framework",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.11",
   "description": "Oriel: a Laravel-style, full-stack TypeScript framework for Node.js and Bun.",
   "type": "module",
   "license": "Apache-2.0",
@@ -58,35 +58,37 @@
     "pluralize": "8.0.0"
   },
   "devDependencies": {
-    "@orieljs/collections": "0.1.0-alpha.10",
-    "@orieljs/config": "0.1.0-alpha.10",
-    "@orieljs/console": "0.1.0-alpha.10",
-    "@orieljs/cache": "0.1.0-alpha.10",
-    "@orieljs/auth": "0.1.0-alpha.10",
-    "@orieljs/bus": "0.1.0-alpha.10",
-    "@orieljs/database": "0.1.0-alpha.10",
-    "@orieljs/container": "0.1.0-alpha.10",
-    "@orieljs/contracts": "0.1.0-alpha.10",
-    "@orieljs/encryption": "0.1.0-alpha.10",
-    "@orieljs/cookie": "0.1.0-alpha.10",
-    "@orieljs/foundation": "0.1.0-alpha.10",
-    "@orieljs/hashing": "0.1.0-alpha.10",
-    "@orieljs/filesystem": "0.1.0-alpha.10",
-    "@orieljs/events": "0.1.0-alpha.10",
-    "@orieljs/http": "0.1.0-alpha.10",
-    "@orieljs/inertia": "0.1.0-alpha.10",
-    "@orieljs/log": "0.1.0-alpha.10",
-    "@orieljs/mail": "0.1.0-alpha.10",
-    "@orieljs/notifications": "0.1.0-alpha.10",
-    "@orieljs/pipeline": "0.1.0-alpha.10",
-    "@orieljs/queue": "0.1.0-alpha.10",
-    "@orieljs/support": "0.1.0-alpha.10",
-    "@orieljs/live": "0.1.0-alpha.10",
-    "@orieljs/session": "0.1.0-alpha.10",
-    "@orieljs/validation": "0.1.0-alpha.10",
-    "@orieljs/testing": "0.1.0-alpha.10",
-    "@orieljs/view": "0.1.0-alpha.10",
-    "@orieljs/routing": "0.1.0-alpha.10"
+    "@orieljs/auth": "0.1.0-alpha.11",
+    "@orieljs/collections": "0.1.0-alpha.11",
+    "@orieljs/console": "0.1.0-alpha.11",
+    "@orieljs/config": "0.1.0-alpha.11",
+    "@orieljs/contracts": "0.1.0-alpha.11",
+    "@orieljs/container": "0.1.0-alpha.11",
+    "@orieljs/cache": "0.1.0-alpha.11",
+    "@orieljs/bus": "0.1.0-alpha.11",
+    "@orieljs/database": "0.1.0-alpha.11",
+    "@orieljs/cookie": "0.1.0-alpha.11",
+    "@orieljs/encryption": "0.1.0-alpha.11",
+    "@orieljs/events": "0.1.0-alpha.11",
+    "@orieljs/filesystem": "0.1.0-alpha.11",
+    "@orieljs/hashing": "0.1.0-alpha.11",
+    "@orieljs/http": "0.1.0-alpha.11",
+    "@orieljs/inertia": "0.1.0-alpha.11",
+    "@orieljs/live": "0.1.0-alpha.11",
+    "@orieljs/log": "0.1.0-alpha.11",
+    "@orieljs/mail": "0.1.0-alpha.11",
+    "@orieljs/notifications": "0.1.0-alpha.11",
+    "@orieljs/obfuscate": "0.1.0-alpha.11",
+    "@orieljs/pipeline": "0.1.0-alpha.11",
+    "@orieljs/queue": "0.1.0-alpha.11",
+    "@orieljs/support": "0.1.0-alpha.11",
+    "@orieljs/testing": "0.1.0-alpha.11",
+    "@orieljs/foundation": "0.1.0-alpha.11",
+    "@orieljs/validation": "0.1.0-alpha.11",
+    "@orieljs/view": "0.1.0-alpha.11",
+    "@orieljs/routing": "0.1.0-alpha.11",
+    "@orieljs/session": "0.1.0-alpha.11",
+    "@orieljs/vercel": "0.1.0-alpha.11"
   },
   "peerDependencies": {
     "pg": "^8.23.0",