toiljs 0.0.85 → 0.0.87

package/docs/getting-started/deploy.md

@@ -0,0 +1,101 @@
+# Deploying a toiljs app
+
+This page is an honest look at how you get a toiljs app in front of real users. There are two paths, and it helps to be clear about which one exists today.
+
+- **Self-host it yourself.** You build the app and run it on a machine you control, with `toiljs build` then `toiljs start`. This works right now, on your laptop, a VPS, or any server that can run Node.js.
+- **Run it on the managed Dacely edge.** This is the platform toiljs is built for: a worldwide fleet of servers that runs your compiled backend close to every user. It is the target the whole framework is designed around.
+
+One thing up front, so you do not go looking for it: **there is no `toiljs deploy` command.** The CLI can build and self-host; pushing a build onto the managed edge is a platform step, not a CLI subcommand. The rest of this page covers what you can do today (self-hosting) and what the managed edge gives you.
+
+## The one build powers both
+
+Both paths serve the exact same artifacts. `toiljs build` produces them once:
+
+```mermaid
+flowchart LR
+    A["Your project"] -->|toiljs build| B["build/client/<br/>(HTML, JS, CSS, assets)"]
+    A -->|toiljs build| C["build/server/release.wasm<br/>(your backend)"]
+    B --> H["toiljs start<br/>(self-host)"]
+    C --> H
+    B --> E["managed Dacely edge<br/>(worldwide)"]
+    C --> E
+```
+
+So you never build differently for the two targets. You build once, then either run it yourself or hand the same output to the edge.
+
+## Self-hosting with `toiljs start`
+
+`toiljs start` runs your built app on a fast production HTTP server. It serves your static client, dispatches dynamic requests into your `release.wasm`, does server-side rendering, runs daemons, and exposes a `/_toil` websocket channel. Use it to put your app on your own machine or server instead of the managed edge.
+
+### Step 1: build
+
+`start` serves whatever is in `build/`, so you must build first. If there is no build, `start` exits with an error (it looks for `build/client/index.html`).
+
+```bash
+npm run build
+```
+
+### Step 2: start
+
+```bash
+# Serve on http://127.0.0.1:3000 (loopback only, one worker per CPU).
+npx toiljs start
+
+# Accept outside connections, on port 8080, with 4 worker processes.
+npx toiljs start --host 0.0.0.0 --port 8080 --threads 4
+```
+
+### start flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--port <n>` | Port to listen on. Default `3000` (or `client.port` from your config). |
+| `--host <host>` | Address to bind. Default `127.0.0.1`, which is **loopback only** (reachable just from the same machine). Pass `0.0.0.0` to accept connections from other machines. |
+| `--threads <n>` | Number of HTTP worker processes. Default is automatic (one per available CPU). Pass `1` to disable the worker pool. `--workers` is an accepted alias, and you can also set `server.threads` in your config or the `TOILJS_THREADS` environment variable. |
+| `--root <dir>` | Run against a project in another directory instead of the current one. |
+
+These flags are verified against the CLI. Note that `--host` and `--threads` are `start`-only: `toiljs dev` always binds locally and does not take them. For the full command reference, see [the CLI](../cli/README.md#toiljs-start).
+
+### A realistic self-host
+
+On a small server (say a VPS), a minimal run looks like this:
+
+```bash
+# Install and build.
+npm ci
+npm run build
+
+# Bind on all interfaces so a reverse proxy or the public can reach it.
+npx toiljs start --host 0.0.0.0 --port 8080 --threads 4
+```
+
+Then put a reverse proxy (nginx, Caddy) in front for TLS and a real hostname, pointing it at `http://127.0.0.1:8080`. Keep the process alive with your usual tool (systemd, pm2, a container restart policy).
+
+### Self-host gotchas
+
+- **`start` needs a fresh build.** It serves `build/`, not your source. After any code change, run `toiljs build` again before restarting.
+- **The default bind is loopback.** With no `--host`, only the same machine can reach it. Set `--host 0.0.0.0` (usually behind a reverse proxy) to serve real traffic.
+- **Self-host is one place, not the whole world.** You get one server (or however many you run yourself). The latency and worldwide reach of the managed edge is exactly the thing self-hosting does not give you.
+- **The database is different.** Self-hosting runs the built server, but ToilDB's worldwide data layer is an edge feature. Treat self-host as a way to run and test your build, not as a substitute for the managed edge's global database.
+
+## The managed Dacely edge
+
+The managed **Dacely edge** is the platform toiljs targets: a fleet of servers in many cities that runs your compiled backend as close to each user as possible, backed by the worldwide **ToilDB** database. You write one project, and the build already decides which part of your code belongs to which layer of the edge.
+
+Your backend runs across four **compute tiers**, from a per-request handler at the very edge up to a single worldwide coordinator:
+
+| Tier | Name | Where it runs | Typical code |
+| --- | --- | --- | --- |
+| **L1** | Hot / edge | The node nearest the user, fresh per request | `@rest`, `@service` / `@remote` |
+| **L2** | Regional | One box per connection, per region | `@stream` (Regional) |
+| **L3** | Continental | One box per connection, per continent | `@stream` (Continental) |
+| **L4** | Global / daemon | Exactly one leader worldwide | `@daemon`, `@scheduled` |
+
+Because the same `toiljs build` output feeds the edge, everything you built and tested with `toiljs dev` and `toiljs start` is what runs there. The edge decides each server's role for you; you do not configure tiers by hand. For the full picture of what each tier means and how to write for it, see [Compute tiers (L1 to L4)](../concepts/tiers.md).
+
+## Related
+
+- [The CLI](../cli/README.md): the full reference for `build` and `start` and every flag.
+- [Configuration (`toil.config.ts`)](../concepts/config.md): `server.threads` and the other self-host knobs.
+- [Compute tiers (L1 to L4)](../concepts/tiers.md): how your code maps onto the managed edge.
+- [Getting started](./README.md): the path from install to a running feature.

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

@@ -0,0 +1,215 @@
+# 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

@@ -0,0 +1,106 @@
+# 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.
+
+## 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

@@ -0,0 +1,125 @@
+# 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)