toiljs 0.0.115 → 0.0.117

package/docs/getting-started/first-app.md

@@ -1,215 +0,0 @@
-# Your first app
-
-Build a tiny feature end to end: a page with a "Like" button that reads and writes a real number in ToilDB, so the count survives page reloads and restarts. Along the way you meet the typed client, an HTTP route, and the database, the three pieces you use in almost every toiljs app.
-
-## What you will build
-
-A `/likes` page that shows a running like count and a button to add one. The count lives in ToilDB, so it is shared by everyone and it persists.
-
-```mermaid
-sequenceDiagram
-    participant B as Browser (/likes page)
-    participant SH as shared/server.ts (typed client)
-    participant W as server.wasm (@rest route)
-    participant DB as ToilDB (counter)
-    B->>SH: Server.REST.likes.add()
-    SH->>W: POST /likes
-    W->>DB: counter.add(key, 1)
-    W-->>SH: { count: 43 }
-    SH-->>B: typed LikeCount
-    B->>B: show "43 likes"
-```
-
-## Before you start
-
-You need a project. If you do not have one yet, create one and start the dev server:
-
-```sh
-toiljs create my-app
-cd my-app
-npm run dev
-```
-
-Leave `npm run dev` running in a terminal. It rebuilds your server, regenerates the typed client, and hot-reloads the browser every time you save. The app is at `http://localhost:3000`.
-
-## Why the database (and not a variable)
-
-Your first instinct might be to keep the count in a normal variable on the server. That will not work, and it is worth understanding why now.
-
-**The server runs a fresh copy of your `.wasm` for every request, and wipes its memory when the request ends.** So a variable you set while handling one request is gone by the next request. Anything that must outlive a single request, a counter, a user, a post, has to go into a store. toiljs ships one: **ToilDB**, a database built into the edge.
-
-ToilDB offers a few specialized shapes called **families**. For a running total, the right one is a **counter**: a value you can atomically add to and read back. (Others include documents, events, and views. See [Database overview](../database/README.md).)
-
-## Step 1: add a data type for the response
-
-Your server and client talk in typed messages called `@data` classes. A `@data` class can cross the wire and be parsed into a real typed object on the other side. Create one to hold the count.
-
-Create `server/models/LikeCount.ts`:
-
-```ts
-// The response our route returns: just the current like count.
-@data
-export class LikeCount {
-    count: i64 = 0;
-    constructor(count: i64 = 0) {
-        this.count = count;
-    }
-}
-```
-
-Two things to notice:
-
-- `@data` is a decorator that marks this class as a wire type. You use it with no import (it is a compiler built-in). See [Data types](../backend/data.md).
-- The field type is `i64`, a 64-bit integer. The server uses precise integer types like `i64` and `u64`. On the client side these arrive as JavaScript `bigint`. More on this in [Types](../concepts/types.md).
-
-## Step 2: add the HTTP route
-
-Now the backend endpoint. Create `server/routes/Likes.ts`:
-
-```ts
-import { RouteContext } from 'toiljs/server/runtime';
-
-import { LikeCount } from '../models/LikeCount';
-
-// The KEY that names one counter. A counter is a map from a key to a number,
-// so a single fixed key ("home") gives us one global tally.
-@data
-class LikeKey {
-    page: string = 'home';
-    constructor(page: string = 'home') {
-        this.page = page;
-    }
-}
-
-// A @database declares your ToilDB collections. Each @collection is one named
-// store. Here we declare a single counter keyed by LikeKey.
-@database
-class LikesDb {
-    @collection static likes: Counter<LikeKey>;
-}
-
-// A @rest controller exposes HTTP endpoints. 'likes' is the URL prefix, so the
-// routes below live under /likes.
-@rest('likes')
-class Likes {
-    // GET /likes  ->  read the current count.
-    // A @get handler is a "query": it may read but not write. Reading one
-    // counter by its key is a point read, which queries are allowed to do.
-    @get('/')
-    public show(): LikeCount {
-        const key = new LikeKey('home');
-        return new LikeCount(LikesDb.likes.get(key));
-    }
-
-    // POST /likes  ->  add one, then return the new count.
-    // A @post handler is an "action": it may write. `add` bumps the counter.
-    // (A body-less POST takes the RouteContext; we do not need it here.)
-    @post('/')
-    public add(_ctx: RouteContext): LikeCount {
-        const key = new LikeKey('home');
-        LikesDb.likes.add(key, 1);
-        return new LikeCount(LikesDb.likes.get(key));
-    }
-}
-```
-
-What each decorator does:
-
-- **`@rest('likes')`** turns the class into an HTTP controller mounted at `/likes`.
-- **`@get('/')`** and **`@post('/')`** map a method to a verb and path. A `@get` is a read-only **query**; a `@post` is a write-capable **action**. This split is how toiljs keeps expensive or unsafe operations out of read paths.
-- **`@database`** and **`@collection`** declare your ToilDB stores. `Counter<LikeKey>` is a counter you look up by a `LikeKey`.
-
-The counter gives you two operations: `add(key, delta)` to change it and `get(key)` to read it. See [Counters](../database/counters.md) and [HTTP routes](../backend/rest.md) for the full API.
-
-## Step 3: register the route
-
-Open `server/main.ts` and add an import for your new route, next to the others:
-
-```ts
-import './routes/Likes';
-```
-
-The build actually discovers decorated files under `server/` on its own, but importing them from `main.ts` is the convention: it keeps a direct `toilscript` build finding the same code. (Every `app` project already imports its demo routes this way.)
-
-Save. Watch the terminal: `toiljs dev` recompiles the server to wasm and regenerates `shared/server.ts`. A moment later your new endpoint exists, fully typed.
-
-## Step 4: add the client page
-
-Now the frontend. Create `client/routes/likes.tsx`. The file name is the URL, so this page is at `/likes`.
-
-```tsx
-import { useEffect, useState } from 'react';
-
-export default function LikesPage() {
-    // The count is a bigint because the server field is i64.
-    const [count, setCount] = useState(0n);
-
-    // Read the current count once, when the page first loads.
-    useEffect(() => {
-        Server.REST.likes.show().then((res) => setCount(res.count));
-    }, []);
-
-    // Add a like, then update the UI with the fresh count the server returns.
-    const like = async () => {
-        const res = await Server.REST.likes.add();
-        setCount(res.count);
-    };
-
-    return (
-        <main>
-            <h1>{String(count)} likes</h1>
-            <button onClick={like}>Like</button>
-        </main>
-    );
-}
-```
-
-The magic here is `Server.REST.likes`. You never wrote it. toiljs generated it into `shared/server.ts` from your `@rest` controller, so:
-
-- `Server.REST.likes.show()` returns a `Promise<LikeCount>`, and `res.count` is typed for you.
-- `Server.REST.likes.add()` sends the POST and returns the updated `LikeCount`.
-- `Server` is a global in client code, so you do not import it. Its types come from the generated file.
-
-If you rename the route or change its return type on the server, this client code stops type-checking until you fix it. That is the whole point: the browser and the backend cannot silently disagree.
-
-## Step 5: try it
-
-Open `http://localhost:3000/likes`. You should see "0 likes" and a button. Click **Like** a few times and the number climbs.
-
-Now the important test: **reload the page.** The count is still there. Stop the dev server, start it again, reload: still there. That is ToilDB persisting your counter, exactly as it would on the real edge. The same code that ran against the local dev database runs against the worldwide database in production, with no connection string to configure.
-
-## What just happened
-
-```mermaid
-flowchart LR
-    M["server/models/LikeCount.ts<br/>@data"] --> GEN
-    R["server/routes/Likes.ts<br/>@rest + @database"] --> GEN
-    GEN["toiljs dev<br/>compiles + generates"] --> WASM["release.wasm"]
-    GEN --> SS["shared/server.ts<br/>(typed Server.REST.likes)"]
-    SS --> P["client/routes/likes.tsx<br/>calls Server.REST.likes"]
-```
-
-You wrote three small files. toiljs compiled the server to WebAssembly, generated a typed client from your route, and your React page called it with full type safety. The like count lives in ToilDB, so it persists.
-
-## Gotchas and notes
-
-- **`res.count` is a `bigint`, not a `number`.** That is why the page uses `useState(0n)` and `String(count)`. Server integer types map to `bigint` on the client. See [Types](../concepts/types.md).
-- **A `@get` cannot write, and a `@post` can.** If you try to call `.add(...)` from a `@get`, the compiler rejects it. Reads that scan many rows are also blocked in handlers; a single-key `get` is fine.
-- **You do not edit `shared/server.ts`.** It is regenerated on every server build. Change the route, and the client updates itself.
-- **If the editor does not know `Server.REST.likes` yet**, it is because the server has not rebuilt since you added the route. Save a server file (or restart `toiljs dev`) to regenerate `shared/server.ts`.
-- **The counter is global.** Everyone hitting `/likes` shares the same "home" tally, because we used one fixed key. Use a different key per page or per user to split the count.
-
-## Where to go next
-
-- Return richer objects and lists: [Data types](../backend/data.md) and [HTTP routes](../backend/rest.md).
-- Call the server without URLs, as plain function calls: [Typed RPC](../backend/rpc.md).
-- Store more than a number: [Documents](../database/documents.md), [Events](../database/events.md), and [Views](../database/views.md).
-- Add login and sessions: [Auth](../auth/README.md).
-- Style your pages: [Styling](../frontend/styling.md) and [Routing](../frontend/routing.md).
-
-## Related
-
-- [Project structure](./project-structure.md)
-- [Database overview](../database/README.md)
-- [Counters](../database/counters.md)
-- [Backend overview](../backend/README.md)

package/docs/getting-started/installation.md

@@ -1,124 +0,0 @@
-# Installation
-
-Install the toiljs command-line tool (CLI) so you can create and run projects. This takes a couple of minutes.
-
-## Why and when
-
-You need the toiljs CLI once, before you create your first project. The CLI is the single tool you use to scaffold, run, build, and check toiljs apps. After a project exists, the same CLI is also installed inside that project, so day-to-day you can run it through your package scripts (`npm run dev`) without a global install.
-
-## Prerequisites
-
-You need **Node.js version 24.0.0 or newer**. Node.js is the JavaScript runtime that powers the toiljs CLI, the dev server, and the build. (Your backend does not run on Node.js, but the tools that build it do.)
-
-Check your version:
-
-```sh
-node --version
-```
-
-If it prints `v24.0.0` or higher, you are set. If it is older or the command is not found, install a current Node.js from [nodejs.org](https://nodejs.org), or use a version manager like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm):
-
-```sh
-# with nvm
-nvm install 24
-nvm use 24
-```
-
-You also need a package manager. **npm** comes with Node.js, so you already have it. toiljs also supports **pnpm**, **yarn**, and **bun** if you prefer one of those.
-
-### TypeScript 6, not 7
-
-toiljs requires **TypeScript 6** (`>=6.0.0 <7.0.0`). TypeScript 7 is not supported yet.
-
-TypeScript 7 is the native (Go) port of the compiler. It ships a much faster `tsc`, but its package no longer exports the JavaScript compiler API, whose main entry is now just `{ version, versionMajorMinor }`. toiljs reads each route's static `metadata` export through that API to bake your SEO tags into the built HTML, and the `toiljs/eslint` preset loads it too. On TypeScript 7 the metadata baking silently stops (your built pages lose their tags) and typescript-eslint fails to load at all.
-
-Pin TypeScript in your `package.json`:
-
-```json
-{
-    "devDependencies": {
-        "typescript": "^6.0.3"
-    }
-}
-```
-
-`toiljs doctor` flags an unsupported TypeScript, and `toiljs doctor --fix` pins it back for you. `toiljs update` will not upgrade you into TypeScript 7. Support will land once the tools toiljs builds on can read the new `typescript/unstable/*` API.
-
-## Install the CLI
-
-The package is called `toiljs`, and it provides a command named `toiljs`. You have two ways to use it.
-
-### Option A: run it on demand with npx (no install)
-
-`npx` comes with npm and runs a package without installing it globally. This is the quickest way to create your first project:
-
-```sh
-npx toiljs create my-app
-```
-
-### Option B: install it globally
-
-If you plan to create projects often, install it once so `toiljs` is always on your path:
-
-```sh
-npm install -g toiljs
-```
-
-Then you can run `toiljs` directly:
-
-```sh
-toiljs create my-app
-```
-
-Both options end up at the same place. The rest of these docs write `toiljs <command>`; if you did not install globally, just put `npx` in front (`npx toiljs <command>`).
-
-## Verify it works
-
-Check the version:
-
-```sh
-toiljs --version
-```
-
-You should see a version number printed (for example, `0.0.86`).
-
-To see every command and flag, run help:
-
-```sh
-toiljs --help
-```
-
-Inside a project, there is a deeper health check called **doctor**. It inspects your setup and dependencies and tells you exactly what to fix. You will use it after you create a project, but it is good to know it exists:
-
-```sh
-toiljs doctor
-```
-
-`toiljs doctor` reads your project (its `package.json`, config, routes, and build output), runs a series of checks, and prints a grouped report. One of the first checks is your Node.js version against the required `>=24.0.0`, so if your Node is too old, doctor will say so. Add `--fix` to let it repair the things it can (such as the typed-RPC wiring), or `--json` for machine-readable output in a CI pipeline.
-
-## How the tooling fits together
-
-The `toiljs` CLI is a friendly front end over two underlying tools. You rarely call them directly, but it helps to know they exist.
-
-```mermaid
-flowchart LR
-    CLI["toiljs CLI"] --> TS["toilscript<br/>(compiles server/ to wasm)"]
-    CLI --> VITE["Vite<br/>(bundles client/ React)"]
-    TS --> W["build/server/release.wasm"]
-    VITE --> B["build/client/"]
-```
-
-When you create a project, both `toiljs` and `toilscript` are added to it as dependencies, so everything is pinned to versions that work together. You do not install `toilscript` separately.
-
-## Gotchas and notes
-
-- **"command not found: toiljs"** after a global install usually means npm's global bin folder is not on your `PATH`. Either fix your `PATH` or just use `npx toiljs ...` instead.
-- **Node too old** is the most common first-time failure. WebAssembly tooling and the build depend on features in Node 24 and up. Upgrade before creating a project.
-- **Every command checks for updates.** On each run, the CLI quietly checks npm for a newer toiljs and prints a note if you are behind. It never blocks the command. To turn it off, set the environment variable `TOILJS_NO_UPDATE_CHECK=1`.
-- You do **not** need to install a database, a Docker container, or any cloud account to develop locally. The dev server includes a local ToilDB so your data-backed features run out of the box.
-
-## Related
-
-- [Create a project](./create-project.md)
-- [The CLI reference](../cli/README.md)
-- [Getting started overview](./README.md)

package/docs/getting-started/migrating.md

@@ -1,125 +0,0 @@
-# Migrating an existing React app
-
-How to bring a React app you already have into toiljs. The frontend usually moves over with small changes. The backend is the real work, because a toiljs server is not Node.js, and this page is honest about what that means.
-
-## Why and when
-
-Move to toiljs when you want your frontend and backend in one typed repo, deployed to the edge, with a built-in global database, and you are willing to rewrite your server logic against toiljs's rules. If you only want a React bundler, toiljs is more than you need. If you want the full-stack, typed, edge model, this is the payoff.
-
-The safest approach is **not** to convert your old project in place. Instead, scaffold a fresh toiljs project and move code into it piece by piece. A fresh project comes with the required presets, config, and routing already wired, so you spend your time on your code, not on plumbing.
-
-```sh
-toiljs create my-app
-cd my-app
-```
-
-## The big picture: what moves where
-
-```mermaid
-flowchart LR
-    subgraph OLD["Your current app"]
-        FE["React components,<br/>pages, styles, assets"]
-        BE["Node/Express backend,<br/>DB access, npm libs"]
-    end
-    FE -->|"mostly copy"| C["toiljs client/"]
-    BE -->|"rewrite"| S["toiljs server/"]
-    C -.->|"generated typed client"| S
-    S --> DB[("ToilDB")]
-```
-
-- Your **React frontend** copies into `client/` with modest changes (routing and asset paths).
-- Your **backend** is **rewritten** into `server/` as toilscript, because it compiles to WebAssembly, not Node.
-
-## The frontend: what changes
-
-`client/` is a normal Vite + React app, so most of your frontend works as is. The common adjustments:
-
-- **Routing becomes file-based.** toiljs has no `<Routes>`/`<Route>` config. A file at `client/routes/about.tsx` is the `/about` page; `client/routes/blog/[slug].tsx` is `/blog/:slug`. Move each page component to the matching file and delete your router setup. Use `Toil.Link` for navigation instead of your router's `Link`. See [Routing](../frontend/routing.md).
-- **Static assets move to `client/public/`.** Files there are served as is (images at `/images/...`, plus `favicon` and `robots.txt`).
-- **Global styles move to `client/styles/`**, and are imported from `client/toil.tsx`. See [Styling](../frontend/styling.md).
-- **Your React npm packages are fine.** The client is regular JavaScript, so component libraries, state managers, and browser APIs all work.
-- **Data fetching changes** if you want the typed client: replace hand-written `fetch('/api/...')` calls with the generated `Server.REST.*` methods. You can keep raw `fetch` too, but you lose the type safety. See [Fetching data](../frontend/data-fetching.md).
-
-Metadata and SEO that you used a helmet library for is built in: set a `metadata` export per route, or use `Toil.Head`. See [Metadata and SEO](../frontend/metadata.md).
-
-## The backend: the honest part
-
-This is where migration takes real effort. Read this section carefully before you plan the work.
-
-Your toiljs server is compiled by **toilscript** into WebAssembly. toilscript accepts a **strict subset of TypeScript**. It looks like TypeScript, but treat it as a small, separate language that happens to share the syntax. The practical consequences:
-
-### What is NOT available on the server
-
-- **No arbitrary npm packages.** You cannot `import` a library from `node_modules` into `server/`. There is no `express`, no `pg`, no `stripe` SDK, no `lodash`. If your route logic leans on npm libraries, that logic has to be reworked.
-- **No Node.js APIs.** No `fs`, `http`, `process`, `Buffer`, `path`, or other Node built-ins. The server runs in a sandbox, not in Node.
-- **No DOM or browser APIs**, because it is not a browser either.
-- **No connecting to your existing database.** There is no connection string and no driver. Your data moves to **ToilDB**, the built-in database.
-
-### What you use instead
-
-toiljs replaces the common needs with built-in globals and decorators, so you rarely miss the missing libraries:
-
-| You used to reach for | On the toiljs server you use |
-| --- | --- |
-| `express` routes / a router | `@rest` controllers with `@get` / `@post` ([HTTP routes](../backend/rest.md)) |
-| A REST client between services | `@service` / `@remote` typed RPC ([RPC](../backend/rpc.md)) |
-| Postgres / Mongo / Redis | [ToilDB](../database/README.md) families (documents, counters, events, views) |
-| `jsonwebtoken`, session middleware | Built-in [auth](../auth/README.md) and cookies |
-| `crypto` from Node | the `crypto` global (synchronous Web Crypto) ([Crypto](../services/crypto.md)) |
-| `nodemailer` / an email SDK | the built-in email service ([Email](../services/email.md)) |
-| `process.env` | `Environment.get()` / `Environment.getSecure()` ([Environment](../services/environment.md)) |
-| `Date.now()`, timers | the `Time` global ([Time](../services/time.md)) |
-
-### Type system differences
-
-toilscript uses precise, explicit numeric types instead of JavaScript's single `number`. You will write `i32`, `u64`, `f64`, and even `u256`, and be explicit about integer sizes. Values that must cross the wire are `@data` classes with concrete fields, not free-form objects. There is no `any`-style duck typing to lean on. The full rules, and how server types map to `bigint` and friends on the client, are in [Types](../concepts/types.md).
-
-### Two behaviors to design around
-
-- **Memory resets every request.** Each request gets a fresh `.wasm` instance and its memory is wiped afterward. A module-level variable does not persist. Anything durable goes in ToilDB. (This is the same rule you met in [Your first app](./first-app.md).)
-- **Reads and writes are split.** A `@get` is a read-only query; a `@post` is a write action. Operations that scan unbounded data are not allowed in a request handler; they move to a [`@derive`](../background/derive.md) or a background [daemon](../background/daemons.md).
-
-## Configuration
-
-Two config files replace the various configs you may have had:
-
-- **`toil.config.ts`** is your client and build config: SEO defaults, image optimization, page transitions, and dev-server options. It uses `defineConfig`. See [Configuration](../concepts/config.md).
-- **`toilconfig.json`** is the low-level server (wasm) build config. The scaffold sets sensible defaults, and you usually leave it alone.
-
-Environment variables move from a `.env` you read with `process.env` to `.env` / `.env.secrets` files you read with `Environment.get()` / `Environment.getSecure()`. Secrets and plain vars are kept in separate buckets. See [Environment and secrets](../services/environment.md).
-
-## Step by step
-
-1. **Scaffold a fresh project** with `toiljs create` and get it running with `npm run dev`. Start from something that works.
-2. **Move the frontend.** Copy components into `client/components/`, turn each page into a file under `client/routes/`, move styles into `client/styles/`, and static assets into `client/public/`. Swap your router's `Link` for `Toil.Link`. Install your client-side npm dependencies.
-3. **Get the client rendering** against the routes, even if the data is still stubbed or points at your old backend. Fix routing and asset paths first.
-4. **Rebuild the backend, one route at a time.** For each old endpoint, add a `@data` model in `server/models/`, a `@rest` controller in `server/routes/`, and move its data into a ToilDB family. Import each new route in `server/main.ts`. This is the bulk of the effort; go endpoint by endpoint.
-5. **Move persistence to ToilDB.** Map each table or collection to a ToilDB family (a document store, a counter, an event log, or a view). See [Database overview](../database/README.md) for choosing a family.
-6. **Switch the client to the typed client.** Replace `fetch('/api/...')` calls with `Server.REST.*` (or `Server.<service>.*` for RPC). Now a backend change that breaks the contract shows up as a client type error.
-7. **Run the doctor.** `toiljs doctor` checks your wiring (routes, RPC generation, config, dependencies) and points at anything still off. Add `--fix` to let it repair what it can.
-
-## When toiljs is not the right move
-
-Be honest with yourself about the backend rewrite. Migration is a poor fit if:
-
-- Your server depends heavily on npm libraries or Node-only APIs that have no toiljs equivalent, and rewriting them is not worth it.
-- You must keep talking to an existing external database or service that toiljs cannot reach. (Daemons can make outbound HTTP calls in some cases, but general server-side networking is limited by design.)
-- You need long-lived in-process server state that does not fit the per-request, database-backed model.
-
-In those cases, you can still adopt toiljs for the frontend and keep your existing backend, calling it with plain `fetch`. You just give up the single-repo, end-to-end-typed benefits for that part.
-
-## Gotchas and notes
-
-- **Do not try to `import` server code into the client or vice versa.** They compile with different rules. The only bridge is the generated `shared/server.ts`.
-- **One `@data` type per file** under `models/` matches the tooling's expectations.
-- **`shared/server.ts` is generated**, so it will not exist until your first build, and you never edit it.
-- **Plan the backend as a rewrite, not a port.** The frontend moves; the backend is re-expressed in toiljs's model. Budget for that.
-
-## Related
-
-- [Getting started overview](./README.md)
-- [Backend overview](../backend/README.md)
-- [Types](../concepts/types.md)
-- [Database overview](../database/README.md)
-- [The CLI reference](../cli/README.md)
-- [Configuration](../concepts/config.md)

package/docs/getting-started/project-structure.md

@@ -1,163 +0,0 @@
-# Project structure
-
-A tour of every folder and file in a toiljs project, what each one is for, and the single most important question: **where does this code run, the browser or the edge?**
-
-## Why this matters
-
-toiljs blends frontend and backend into one repo, so the same `.ts` file extension can mean two very different things. A file in `client/` becomes JavaScript that runs in your user's browser. A file in `server/` becomes WebAssembly that runs on the edge, with different rules and different available APIs. Knowing which folder you are in tells you what you are allowed to do. Keep this mental split and everything else falls into place.
-
-```mermaid
-flowchart TD
-    subgraph Browser["Runs in the browser"]
-        C["client/*"]
-    end
-    subgraph Edge["Runs on the edge (WebAssembly)"]
-        S["server/*  ->  release.wasm"]
-    end
-    subgraph Generated["Generated glue (types + config)"]
-        SH["shared/server.ts"]
-        CFG["toil.config.ts / toilconfig.json"]
-    end
-    C -. "typed calls" .-> SH
-    SH -. "HTTP / realtime" .-> S
-    S --> DB[("ToilDB")]
-```
-
-## The top level
-
-These files sit in your project root.
-
-| File | What it is | Runs where |
-| --- | --- | --- |
-| `package.json` | Scripts (`dev`, `build`, `lint`, `typecheck`, `format`) and dependencies (`toiljs`, `react`, `toilscript`, ...) | tooling only |
-| `toil.config.ts` | **Client and build config.** Uses `defineConfig` to set SEO, images, page transitions, and dev options. | tooling only |
-| `toilconfig.json` | **Server (wasm) build config** for toilscript: the entry file, the output `.wasm` path, and low-level compile options. You rarely edit this. | tooling only |
-| `tsconfig.json` | TypeScript config for the client (`client/`, `shared/`, `emails/`). Extends `toiljs/tsconfig`. | tooling only |
-| `eslint.config.js` | Linting preset (`toiljs/eslint`). | tooling only |
-| `.prettierrc` | Formatting preset (`toiljs/prettier`). | tooling only |
-| `.prettierignore` | Files Prettier should skip (generated files). | tooling only |
-| `.gitignore` | Ignores `build/`, `.toil/`, generated files, and your `.env` files. | tooling only |
-| `.vscode/settings.json` | Tells VS Code to use the project's TypeScript so the toilscript editor plugin loads. | editor only |
-| `toil-env.d.ts` | **Generated** editor types for client globals like `Toil.Link` and `Toil.Image`. Do not edit. | editor only |
-| `toil-routes.d.ts` | **Generated** list of your real route names, so `Toil.Link href="..."` type-checks. Filled in on the first build. | editor only |
-| `README.md` | Your project's readme. | docs |
-| `CLAUDE.md`, `AGENTS.md`, etc. | Optional AI-assistant hint files that point tools at the toiljs docs. | docs |
-
-Two folders you may also see at the root:
-
-- **`.toil/`** is a working directory toiljs manages (a build cache and a copy of the docs). It is gitignored. You never edit it.
-- **`.env` and `.env.secrets`** are files **you** create when you need local environment variables or secrets during `toiljs dev`. They are gitignored so you never commit them, and the edge loads their real values out of band in production. Your server reads them with `Environment.get("KEY")` and `Environment.getSecure("KEY")`. See [Environment and secrets](../services/environment.md).
-
-## `client/` (runs in the browser)
-
-This is a normal React app. You can use React libraries and browser APIs here freely.
-
-```text
-client/
-  toil.tsx              the entry point; mounts your app
-  layout.tsx            the root layout wrapping every page
-  404.tsx               the not-found page
-  global-error.tsx      the top-level error page
-  routes/               file-based pages
-  components/           shared React components
-  styles/               global stylesheets
-  public/               static files served as-is
-```
-
-- **`toil.tsx`** is the entry file. It imports your global styles and calls `Toil.mount(...)` to start the app. You rarely change it beyond the style imports.
-- **`layout.tsx`** is your root layout: the header, footer, and page shell that wrap every route. Its `children` prop is the current page.
-- **`404.tsx`** renders when no route matches. **`global-error.tsx`** renders when a route throws.
-- **`routes/`** is where pages live, and the file name **is** the URL. `routes/index.tsx` is `/`, `routes/about.tsx` is `/about`, `routes/blog/[slug].tsx` is `/blog/:slug`. This is called **file-based routing**. See [Routing](../frontend/routing.md).
-- **`components/`** holds React components you reuse across pages. Nothing here is a route.
-- **`styles/`** holds your global CSS (or Sass, Less, or Stylus, if you chose one). See [Styling](../frontend/styling.md).
-- **`public/`** holds static files served exactly as they are: `favicon`, `robots.txt`, and an `images/` folder (reachable at `/images/...`). The `public/index.html` is the base HTML shell your app mounts into.
-
-A single global, `Toil`, is available in client code without an import (for `Toil.Link`, `Toil.Image`, and `Toil.Head`). It is typed by the generated `toil-env.d.ts`.
-
-## `server/` (runs on the edge, as WebAssembly)
-
-This is your backend. It is compiled by toilscript into one `.wasm` file. Remember the two rules: **memory resets every request**, and **this is not Node.js** (a strict TypeScript subset, no arbitrary npm packages). See [Backend overview](../backend/README.md) and [Types](../concepts/types.md).
-
-```text
-server/
-  main.ts               the entry: wires the handler + imports your modules
-  tsconfig.json         server-only TS config (loads the toilscript editor plugin)
-  toil-server-env.d.ts  generated editor types for server globals
-  core/                 your request handler and shared logic
-  models/               @data classes
-  routes/               @rest controllers (HTTP)
-  services/             @service / @remote (typed RPC)
-  migrations/           ToilDB schema migrations
-  scheduled/            reserved for scheduled tasks
-```
-
-- **`main.ts`** is the entry the build compiles. It does three required things: it sets `Server.handler` (a factory that returns one fresh handler per request), it re-exports the wasm entry points (`export * from 'toiljs/server/runtime/exports'`), and it defines the `abort` hook. It also `import`s your other server modules so a direct toilscript run builds the same code.
-- **`core/`** holds your top-level `ToilHandler` (often `AppHandler.ts`): the first code that sees each request. It can dispatch to your `@rest` controllers and then fall through to any hand-written logic.
-- **`models/`** holds your `@data` classes, one type per file. A `@data` class is a typed message that can cross the wire between client and server (and into ToilDB). See [Data types](../backend/data.md).
-- **`routes/`** holds your `@rest` controllers: classes decorated with `@rest`, `@get`, and `@post` that expose HTTP endpoints. See [HTTP routes](../backend/rest.md).
-- **`services/`** holds `@service` classes and free `@remote` functions: typed remote calls the client makes as plain function calls (no URLs). See [Typed RPC](../backend/rpc.md).
-- **`migrations/`** holds ToilDB schema migrations. When you change the shape of a stored `@data` type, you add a `<Type>.migration.ts` here that carries old records forward. The compiler enforces this convention. See [Documents](../database/documents.md).
-- **`scheduled/`** is reserved for scheduled tasks. New decorated files anywhere under `server/` are picked up automatically by the build.
-- **`tsconfig.json`** and **`toil-server-env.d.ts`** are editor-support files. They teach your editor about the server globals (`crypto`, `Cookie`, `Environment`, and friends) so it stops flagging them. They do not affect the build.
-
-### How the build discovers your server code
-
-You do not register routes in a config file. The compiler scans every `.ts` file under `server/` and picks up anything that declares a decorated surface (`@rest`, `@service`, `@remote`, `@data`, `@user`, `@database`, and so on). Importing those files from `main.ts` is still good practice: it keeps a direct `toilscript` run building the exact same server.
-
-## `shared/` (generated glue)
-
-```text
-shared/
-  server.ts             GENERATED typed client (do not edit)
-```
-
-**`shared/server.ts` is written for you** by the server build. It contains:
-
-- A typed `Server` object the browser uses to call your backend: `Server.REST.*` for HTTP routes and `Server.<service>.*` for RPC.
-- The client-side codecs for every `@data` class, so responses come back as real typed objects.
-- A `getUser()` helper for reading the signed-in user on the client.
-
-Because it is generated, it does not exist in a fresh project and it is gitignored. It appears the first time you run `toiljs dev` or `toiljs build`. Never hand-edit it; change your server code and it regenerates.
-
-## `build/` (compiled output)
-
-```text
-build/
-  server/release.wasm   your compiled backend (+ release.wat, a readable text form)
-  client/               the bundled React app (from Vite)
-```
-
-This is what actually ships. It is gitignored and recreated by `toiljs build`. You do not edit anything here.
-
-## Putting it together: one request
-
-```mermaid
-sequenceDiagram
-    participant B as Browser (client/)
-    participant SH as shared/server.ts
-    participant W as server.wasm (server/)
-    participant DB as ToilDB
-    B->>SH: Server.REST.likes.like()
-    SH->>W: HTTP POST /likes
-    W->>DB: counter.add(key, 1)
-    W-->>SH: typed LikeCount response
-    SH-->>B: { count }
-```
-
-The browser calls a typed method, the generated client turns it into an HTTP request, your `.wasm` handles it and touches ToilDB, and a typed result comes back. You wrote both ends; the middle is generated.
-
-## Gotchas and notes
-
-- **A `.ts` file's folder decides its rules.** The same code that works in `client/` may not compile in `server/`, because the server is a strict subset without Node APIs.
-- **Do not edit generated files.** `shared/server.ts`, `toil-env.d.ts`, `toil-routes.d.ts`, and `toil-server-env.d.ts` are all regenerated by the build and will overwrite your changes.
-- **One `@data` type per file** under `models/` keeps things tidy and matches the convention the tooling expects.
-- **`build/` and `.toil/` are disposable.** Delete them and the next build recreates them.
-
-## Related
-
-- [Your first app](./first-app.md)
-- [Frontend overview](../frontend/README.md) and [Routing](../frontend/routing.md)
-- [Backend overview](../backend/README.md)
-- [Database overview](../database/README.md)
-- [Configuration](../concepts/config.md)
-- [Decorators reference](../concepts/decorators.md)