npm - toiljs - Versions diffs - 0.0.85 → 0.0.87 - Mend

toiljs 0.0.85 → 0.0.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (132) hide show

package/CHANGELOG.md +5 -0
package/README.md +2 -2
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +303 -293
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/config.d.ts +2 -0
package/build/compiler/config.js +1 -0
package/build/compiler/docs.js +8 -24
package/build/compiler/generate.js +4 -2
package/build/compiler/index.d.ts +1 -1
package/build/compiler/index.js +69 -6
package/build/compiler/toil-docs.generated.js +64 -22
package/build/devserver/.tsbuildinfo +1 -1
package/build/devserver/analytics/index.js +7 -3
package/build/devserver/db/database.d.ts +4 -0
package/build/devserver/db/database.js +43 -1
package/build/devserver/db/index.d.ts +1 -1
package/build/devserver/db/index.js +1 -1
package/build/devserver/db/types.d.ts +3 -0
package/build/devserver/db/types.js +2 -0
package/build/devserver/runtime/module.js +4 -1
package/docs/README.md +104 -65
package/docs/auth/README.md +102 -0
package/docs/auth/configuration.md +94 -0
package/docs/auth/extending.md +202 -0
package/docs/auth/how-it-works.md +138 -0
package/docs/auth/usage.md +188 -0
package/docs/backend/README.md +143 -0
package/docs/backend/data.md +351 -0
package/docs/backend/rest.md +402 -0
package/docs/backend/rpc.md +226 -0
package/docs/background/README.md +114 -0
package/docs/background/daemons.md +230 -0
package/docs/background/derive.md +179 -0
package/docs/cli/README.md +377 -0
package/docs/concepts/config.md +416 -0
package/docs/concepts/decorators.md +127 -0
package/docs/concepts/security.md +108 -0
package/docs/concepts/tiers.md +166 -0
package/docs/concepts/types.md +216 -0
package/docs/database/README.md +143 -0
package/docs/database/capacity.md +350 -0
package/docs/database/counters.md +174 -0
package/docs/database/documents.md +255 -0
package/docs/database/events.md +307 -0
package/docs/database/membership.md +246 -0
package/docs/database/setup.md +155 -0
package/docs/database/unique.md +216 -0
package/docs/database/views.md +246 -0
package/docs/frontend/README.md +101 -0
package/docs/frontend/data-fetching.md +243 -0
package/docs/frontend/images.md +148 -0
package/docs/frontend/metadata.md +344 -0
package/docs/frontend/rendering.md +236 -0
package/docs/frontend/routing.md +344 -0
package/docs/frontend/scripts.md +118 -0
package/docs/frontend/search.md +191 -0
package/docs/frontend/styling.md +147 -0
package/docs/getting-started/README.md +81 -0
package/docs/getting-started/create-project.md +131 -0
package/docs/getting-started/deploy.md +101 -0
package/docs/getting-started/first-app.md +215 -0
package/docs/getting-started/installation.md +106 -0
package/docs/getting-started/migrating.md +125 -0
package/docs/getting-started/project-structure.md +163 -0
package/docs/introduction/README.md +41 -0
package/docs/introduction/design-principles.md +55 -0
package/docs/introduction/distributed.md +74 -0
package/docs/introduction/how-it-works.md +74 -0
package/docs/introduction/hyperscale.md +51 -0
package/docs/introduction/modern-stack.md +36 -0
package/docs/introduction/vs-other-frameworks.md +48 -0
package/docs/introduction/why-toil.md +93 -0
package/docs/llms.txt +90 -0
package/docs/realtime/README.md +102 -0
package/docs/realtime/channels.md +211 -0
package/docs/realtime/streams.md +369 -0
package/docs/services/README.md +60 -0
package/docs/services/analytics.md +268 -0
package/docs/services/caching.md +175 -0
package/docs/services/cookies.md +235 -0
package/docs/services/crypto.md +209 -0
package/docs/services/email.md +289 -0
package/docs/services/environment.md +141 -0
package/docs/services/ratelimit.md +174 -0
package/docs/services/time.md +85 -0
package/examples/basic/client/routes/analytics.tsx +13 -12
package/examples/basic/server/models/SiteAnalytics.ts +29 -17
package/examples/basic/server/routes/Analytics.ts +15 -17
package/examples/basic/server/routes/UserId.ts +22 -0
package/package.json +15 -11
package/scripts/gen-toil-docs.mjs +24 -35
package/server/auth/AuthController.ts +336 -0
package/server/auth/AuthUser.ts +23 -0
package/server/auth/index.ts +16 -0
package/server/globals/auth.ts +31 -0
package/server/globals/userid.ts +107 -0
package/src/compiler/config.ts +13 -0
package/src/compiler/docs.ts +16 -33
package/src/compiler/generate.ts +6 -2
package/src/compiler/index.ts +114 -6
package/src/compiler/toil-docs.generated.ts +64 -22
package/src/devserver/analytics/index.ts +10 -4
package/src/devserver/db/database.ts +67 -1
package/src/devserver/db/index.ts +1 -0
package/src/devserver/db/types.ts +13 -0
package/src/devserver/runtime/module.ts +7 -0
package/test/analytics-dev.test.ts +2 -1
package/test/devserver-database.test.ts +113 -0
package/docs/auth-todo.md +0 -149
package/docs/auth.md +0 -322
package/docs/caching.md +0 -115
package/docs/cli.md +0 -17
package/docs/client.md +0 -39
package/docs/cookies.md +0 -457
package/docs/crypto.md +0 -130
package/docs/daemon.md +0 -123
package/docs/data.md +0 -131
package/docs/derive.md +0 -159
package/docs/email.md +0 -326
package/docs/environment.md +0 -97
package/docs/getting-started.md +0 -128
package/docs/index.md +0 -30
package/docs/ratelimit.md +0 -95
package/docs/routing.md +0 -259
package/docs/rpc.md +0 -149
package/docs/server.md +0 -61
package/docs/ssr.md +0 -632
package/docs/streams.md +0 -178
package/docs/styling.md +0 -22
package/docs/tiers.md +0 -133
package/docs/time.md +0 -43

package/docs/frontend/scripts.md ADDED Viewed

@@ -0,0 +1,118 @@
+# Scripts
+`Toil.Script` loads an external or inline `<script>` for you, with control over *when* it runs and a guarantee it runs only *once* across your whole app. Use it instead of a hand-written `<script>` tag for third-party snippets (analytics, chat widgets, embeds). It is the toiljs analog of Next.js `next/script`.
+## Why not just write a `<script>` tag?
+Dropping a raw `<script>` into your JSX is unreliable in a single-page app (an app where the browser loads one HTML shell and JavaScript swaps pages in place, with no full reload). Two problems:
+1. **It may not execute.** When React inserts a `<script>` element into the page, the browser does not always run it the way it runs scripts present in the original HTML.
+2. **It runs too often.** As the user navigates between routes that both render that script, React can mount it more than once, so an analytics library or a widget initialises twice.
+`Toil.Script` fixes both: it injects a real `<script>` into `<head>` so the browser runs it, and it **deduplicates** by a key so a given script executes at most once for the whole life of the app, even across client-side navigations. It renders nothing into your layout.
+## The simplest usage: an external script
+Give it a `src`. By default it loads once the app is interactive, which is right for most third-party scripts:
+```tsx
+// client/layout.tsx
+import { type ReactNode } from 'react';
+export default function Layout({ children }: { children?: ReactNode }) {
+  return (
+    <div className="app">
+      <Toil.Script src="https://cdn.example-analytics.com/analytics.js" />
+      {children}
+    </div>
+  );
+}
+```
+Putting it in the root layout means it loads once for the whole app and stays loaded as the user navigates. For an external script, the dedup key defaults to its `src`, so you never need an `id`.
+## Load strategies
+The `strategy` prop decides *when* the script is injected, relative to your app becoming interactive:
+| Strategy | When it runs | Use it for |
+| --- | --- | --- |
+| `afterInteractive` (default) | On mount, once the app is running. | Analytics, chat widgets, most third-party scripts. |
+| `lazyOnload` | Deferred until the browser is idle, after the page's `load` event. | Low-priority extras (a feedback button, a social embed) that should not compete with the initial render. |
+| `beforeInteractive` | As early as possible: injected immediately on first mount. | A script other code depends on immediately. |
+One honest caveat about `beforeInteractive`: a toiljs frontend is a client-only single-page app, so there is no server-rendered `<script>` to run before hydration. `beforeInteractive` therefore still runs *after* hydration, just as early and eagerly as possible on the first mount. It is a priority hint, not a true "before the page is interactive" guarantee.
+```tsx
+<Toil.Script
+  src="https://widget.example.com/embed.js"
+  strategy="lazyOnload"
+/>
+```
+## Inline scripts
+To run a snippet of code instead of loading a URL, put the code in `children` (as a **string**) and give the script an `id`. An inline script has no `src`, so the `id` is what identifies it for dedup, and it is required:
+```tsx
+<Toil.Script id="init-theme" strategy="beforeInteractive">
+  {`document.documentElement.dataset.theme =
+      localStorage.getItem('theme') ?? 'light';`}
+</Toil.Script>
+```
+Without an `id` (and no `src`), an inline script has nothing to dedup on, so `Toil.Script` does nothing at all. This is a deliberate no-op, not an error, so remember the `id`.
+## Reacting to load
+Three optional callbacks let you run code around the script's lifecycle:
+```tsx
+<Toil.Script
+  src="https://widget.example.com/embed.js"
+  strategy="lazyOnload"
+  onReady={() => {
+    // The global the script defines is now available.
+    window.MyWidget?.init();
+  }}
+  onError={(err) => {
+    console.warn('widget failed to load', err);
+  }}
+/>
+```
+- `onLoad` fires **once**, when an external script finishes loading (or an inline script is inserted).
+- `onReady` fires after load **and on every later mount** once the script is already loaded. So if a route that renders the `Toil.Script` is left and revisited, `onReady` runs again, which is the right place to re-initialise a widget.
+- `onError` fires if an **external** script fails to load. After an error the script's key is cleared, so a later remount retries the load.
+## All props
+Read them straight from the source (`src/client/components/Script.tsx`):
+| Prop | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `src` | `string` | (none) | URL of an external script. Omit it when you provide an inline body via `children`. |
+| `children` | `string` | (none) | Inline script body. Mutually exclusive with `src`. |
+| `strategy` | `'beforeInteractive' \| 'afterInteractive' \| 'lazyOnload'` | `'afterInteractive'` | When to inject the script (see above). |
+| `id` | `string` | `src` for external scripts | Stable identity for dedup. **Required** for inline scripts. |
+| `type` | `string` | (none) | The `type` attribute, e.g. `'module'` or `'application/json'`. |
+| `onLoad` | `() => void` | (none) | Fired once the script has loaded (external) or been inserted (inline). |
+| `onReady` | `() => void` | (none) | Fired after load, and on every later mount once the script is already loaded. |
+| `onError` | `(error: unknown) => void` | (none) | Fired if an external script fails to load. |
+External scripts are injected with `async` set, so they never block other work while downloading.
+## Gotchas
+- **Inline scripts need an `id`.** No `id` and no `src` means nothing to dedup on, so the component quietly does nothing.
+- **Dedup is app-wide and survives navigation.** The same `Toil.Script` rendered on two different routes runs a total of once, keyed by `id` (or `src`). This is the point, but it means you cannot use two copies of the same key to run something twice.
+- **Props are read at injection time, and the script re-injects only if its key or strategy changes.** Changing a handler or an inline body *without* changing the `id` will not re-run the script. If you truly need to re-inject a changed inline script, change its `id`.
+- **`onReady` versus `onLoad`.** Use `onLoad` for one-time setup that must happen exactly once; use `onReady` for setup that should also run each time a component remounts against an already-loaded script.
+- **`beforeInteractive` is not truly before hydration** in a client-only app (see the caveat above). Do not rely on it running before your React tree mounts.
+- **`Toil.Script` renders nothing.** It returns `null`, so you can place it anywhere in your component tree; a layout is the usual home for app-wide scripts.
+## Related
+- [Rendering and SSR](./rendering.md): how the client-only app and its first paint fit together.
+- [Metadata and SEO](./metadata.md): for `<head>` tags (title, meta, Open Graph), which is a different job from loading scripts.
+- [Frontend overview](./README.md): the `Toil` global and the rest of the client API.

package/docs/frontend/search.md ADDED Viewed

@@ -0,0 +1,191 @@
+# Page search
+toiljs ships a built-in search over your own pages: at build time it indexes every route's metadata (title, description, keywords, Open Graph), and at runtime you query that index to build a search box or a command palette that jumps straight to a page. It is entirely static (no server, no search service), and there is no equivalent in Next.js, so this page explains it from scratch.
+## What it is
+Every route in your app can export `metadata` (its title, description, and so on, see [Metadata and SEO](./metadata.md)). The toiljs compiler reads that metadata from all your routes at build time and bakes a small **page index** into your bundle: a list of `{ path, title, description, keywords, ... }` for every page. When your app starts, that index is registered in the browser. You can then search it instantly, offline, with zero network calls, and turn a match into a navigation.
+This is what powers a "jump to any page" box or a `Cmd+K` command palette without you maintaining a list of pages or standing up a search backend.
+```mermaid
+flowchart TD
+  A["Your routes<br/>each with export const metadata"] -->|build: scan + extract| B["Static page index<br/>{ path, dynamic, metadata } per page"]
+  B -->|baked into the bundle| C["App startup: Toil.registerPages(index)"]
+  C --> D["Browser: usePageSearch / searchPages query the index"]
+  D --> E["Ranked results -> goTo() navigates"]
+```
+Only **statically-known** metadata is indexed. A route whose `<head>` comes from a dynamic `generateMetadata` (a per-request title) has nothing to index by default; to include it anyway, export `searchHints` (see below).
+## The `usePageSearch` hook
+`usePageSearch` is the React way in. Give it the current query string, and it hands back ranked results plus a helper to navigate:
+```tsx
+const { results, pages, goTo } = Toil.usePageSearch(query);
+```
+It returns an object with three fields:
+| Field | Type | What it is |
+| --- | --- | --- |
+| `results` | `readonly PageSearchResult[]` | The ranked matches for `query`, best first. Empty when the query is blank. |
+| `pages` | `readonly PageMeta[]` | The full page index, handy for showing an "all pages" listing. |
+| `goTo` | `(target, options?) => void` | Navigates to a result, a page, or a raw path string. A stable reference (safe to pass to a child or destructure). |
+Each item in `results` is a `PageSearchResult`:
+- `page`: the matched `PageMeta`, which is `{ path, dynamic, metadata }`. `path` is the route URL (`'/about'`), `dynamic` says whether it has `:param` segments, and `metadata` is the indexed title/description/etc.
+- `score`: a relevance number (higher is better; always above zero for a returned result).
+- `matches`: which fields matched, for example `['title', 'keywords']`.
+The results are memoised, so they recompute only when the query (or options) change, not on every render.
+### A full search box
+Here is a complete search page: an input, a ranked result list, and a click that navigates to the chosen page.
+```tsx
+// client/routes/search.tsx
+import { useState } from 'react';
+export const metadata: Toil.Metadata = {
+  title: 'Search',
+  description: 'Find any page and jump straight to it.',
+  keywords: ['search', 'find', 'pages'],
+};
+export default function SearchPage() {
+  const [query, setQuery] = useState('');
+  const { results, pages, goTo } = Toil.usePageSearch(query);
+  return (
+    <main>
+      <h1>Search</h1>
+      <input
+        type="search"
+        value={query}
+        onChange={(e) => {
+          setQuery(e.target.value);
+        }}
+        placeholder={`Search ${pages.length} pages...`}
+        aria-label="Search pages"
+        autoFocus
+      />
+      {query.trim() !== '' && (
+        <ul>
+          {results.length === 0 && <li>No pages match "{query}".</li>}
+          {results.map((r) => (
+            <li key={r.page.path}>
+              <button
+                type="button"
+                onClick={() => {
+                  goTo(r);
+                }}
+              >
+                <strong>{r.page.metadata.title ?? r.page.path}</strong>{' '}
+                <code>{r.page.path}</code>
+                {r.page.metadata.description !== undefined && (
+                  <p>{r.page.metadata.description}</p>
+                )}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  );
+}
+```
+`goTo` accepts a result (as above), a `PageMeta`, or a plain path string, and takes the same options as `navigate` (see [Routing](./routing.md)). Passing a result is the common case.
+### Options
+`usePageSearch` takes a second argument to tune the search:
+```tsx
+const { results } = Toil.usePageSearch(query, {
+  limit: 8,               // cap the number of results (after ranking)
+  includeDynamic: true,   // include :param routes (see below); default false
+  fields: ['title', 'keywords'], // only match these fields; default all fields
+});
+```
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `limit` | `number` | no cap | Keep only the top N results after ranking. |
+| `includeDynamic` | `boolean` | `false` | Include dynamic (`:param` / `*catch-all`) routes. Off by default because you cannot navigate to them without filling in the params. |
+| `fields` | array of field names | all fields | Restrict matching to a subset of `'title'`, `'description'`, `'keywords'`, `'path'`, `'openGraph'`. |
+## Making dynamic routes searchable with `searchHints`
+A dynamic route like `client/routes/blog/[id].tsx` usually produces its `<head>` with a per-post `generateMetadata`, so there is nothing static to index, and the route is missing from search. To surface it anyway, export `searchHints`: a small static object the compiler merges into the index for that route (winning ties against any static `metadata`).
+```tsx
+// client/routes/blog/[id].tsx
+// The per-post <title> is dynamic, so it cannot be indexed. These static hints
+// put the blog into the search index so it shows up when someone searches "blog".
+export const searchHints: Toil.SearchHints = {
+  title: 'Blog',
+  description: 'Articles and updates.',
+  keywords: ['blog', 'posts', 'articles'],
+};
+```
+`SearchHints` has three optional fields: `title`, `description`, and `keywords` (a string or an array of strings).
+Two things to keep in mind. First, `searchHints` only affects the index; the route is still dynamic, so it appears in results only when you pass `includeDynamic: true`. Second, you cannot `goTo` a dynamic page directly (it needs concrete params), so `goTo` is a no-op for one unless you hand it a real, filled-in path string. In practice you use `searchHints` to make a *section* discoverable (typing "blog" surfaces the blog), and point the user at a concrete landing URL.
+## The lower-level API
+The hook is a thin wrapper over a small, framework-agnostic core you can use directly (outside React, in tests, or to build your own UI). All of these are on the `Toil` global:
+- `Toil.searchPages(query, options?)`: the pure ranking function behind the hook. Returns `PageSearchResult[]`. Same options as the hook.
+- `Toil.getPages()`: the full registered index (`readonly PageMeta[]`), including dynamic routes. Empty before registration.
+- `Toil.pagePath(target)`: normalises a result, a page, or a raw string down to its path string.
+- `Toil.registerPages(pages)`: replaces the live index. toiljs calls this for you at startup with the compiler-built index, so you rarely call it yourself. It exists for tests and advanced setups that build a custom index.
+```tsx
+import { searchPages } from 'toiljs/client';
+// Outside a component: the top 5 title/keyword matches for "billing".
+const hits = searchPages('billing', { limit: 5, fields: ['title', 'keywords'] });
+```
+## How ranking works
+The matcher is simple and predictable:
+- The query is lower-cased and split on whitespace into terms. **Every** term must match somewhere (AND semantics), or the page is dropped. A blank query returns nothing.
+- Matching is case-insensitive and substring-based, with bonuses: an exact field match ranks highest, then a match at the start of the field, then a match at the start of a word inside the field, then a plain mid-word substring.
+- Each field carries a weight, so a hit in the title counts for much more than a hit in the description:
+| Field | Weight |
+| --- | --- |
+| `title` | 10 |
+| `path` | 6 |
+| `keywords` | 5 |
+| `description` | 3 |
+| `openGraph` | 2 |
+- The `path` field is made word-searchable: `/get-started` matches "get" or "started".
+- Results are sorted by score (highest first), ties broken alphabetically by path for a stable order, then cut to `limit` if you set one.
+## Gotchas
+- **Only static metadata is indexed.** A route whose title comes from `generateMetadata` is invisible to search until you add `searchHints`.
+- **Dynamic routes are excluded by default.** They need `includeDynamic: true` to appear, and even then `goTo` cannot navigate to one without concrete params.
+- **The index is built, not live.** It reflects the metadata at build time. Add a route or change a title and you must rebuild for search to see it.
+- **A blank query returns no results**, not every page. If you want an "all pages" listing for an empty box, render `pages` yourself.
+- **The type names** `PageSearchResult`, `PageSearchOptions`, and `SearchField` are importable from `'toiljs/client'` if you need to annotate them; `PageMeta` and `SearchHints` are also available as `Toil.PageMeta` / `Toil.SearchHints`.
+## Related
+- [Metadata and SEO](./metadata.md): the `metadata` the search index is built from.
+- [Routing](./routing.md): route paths, dynamic segments, and `navigate` (what `goTo` calls).
+- [Rendering and SSR](./rendering.md): where `searchHints` fits alongside `generateStaticParams` for dynamic routes.
+- [Frontend overview](./README.md): the `Toil` global and the rest of the client API.

package/docs/frontend/styling.md ADDED Viewed

@@ -0,0 +1,147 @@
+# Styling
+toiljs does not force a styling system on you. It builds with Vite, so you style your app the way you would any Vite + React project: plain CSS, CSS Modules, a preprocessor like Sass, or Tailwind. This page shows the practical options.
+## The one import that matters
+Your app pulls in global styles from the entry file, `client/toil.tsx`:
+```tsx
+// client/toil.tsx
+import { routes, layout, notFound, globalError, slots } from 'toiljs/routes';
+import './styles/main.css';   // <- your global stylesheet
+Toil.mount(routes, layout, notFound, globalError, slots);
+```
+That one import is where your global CSS (resets, CSS variables, base element styles) lives. A typical `client/styles/main.css` sets up theme variables and base styles:
+```css
+/* client/styles/main.css */
+:root {
+  --accent: #2563ff;
+  --bg: #080d11;
+  --text: #f5f6fa;
+}
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.6;
+}
+```
+## Importing CSS anywhere
+You are not limited to the one global sheet. Any component can import its own CSS, and Vite bundles it in:
+```tsx
+// client/components/Card.tsx
+import './card.css';
+export default function Card() {
+  return <div className="card">...</div>;
+}
+```
+The class names in a plain `.css` file are global (they apply everywhere), so name them carefully to avoid clashes, or reach for CSS Modules.
+## CSS Modules (scoped class names)
+If you name a file `*.module.css`, Vite treats it as a **CSS Module**: the class names are locally scoped to the component that imports them, so two components can both use `.title` without colliding. You import the generated names as an object:
+```tsx
+// client/components/Card.tsx
+import styles from './card.module.css';
+export default function Card() {
+  return <div className={styles.card}>...</div>;
+}
+```
+```css
+/* client/components/card.module.css */
+.card {
+  padding: 1rem;
+  border: 1px solid var(--border);
+}
+```
+This is the simplest way to get component-scoped styles with no extra tooling.
+## Preprocessors: Sass, Less, Stylus
+When you create a project (`toiljs create`) you can pick a CSS preprocessor, or add one later to an existing project with the `configure` command:
+```sh
+toiljs configure                 # interactive: choose preprocessor + Tailwind
+toiljs configure --style sass    # switch the preprocessor to Sass
+```
+`configure` installs the right packages and rewrites your style imports for you. After that, `.scss` / `.sass` / `.less` / `.styl` files import exactly like `.css` files, and Vite compiles them.
+## Tailwind
+To use Tailwind (a utility-class CSS framework), turn it on at create time or add it later:
+```sh
+toiljs configure --tailwind
+```
+Tailwind lives in its own stylesheet, `client/styles/tailwind.css`, which is just:
+```css
+@import "tailwindcss";
+```
+`configure` wires that import in for you. From then on you use Tailwind's utility classes directly in your JSX:
+```tsx
+export default function Cta() {
+  return (
+    <button className="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white">
+      Get started
+    </button>
+  );
+}
+```
+## Inline styles and the `style` prop
+Standard React inline styles work as always, and are handy for one-off, dynamic values:
+```tsx
+<div style={{ padding: 24, background: 'var(--surface)' }}>...</div>
+```
+Prefer classes for anything reused; keep inline styles for the truly per-instance case (a computed width, a dynamic color).
+## How types work for style and asset imports
+toiljs generates a `toil-env.d.ts` in your project that declares the import types, so TypeScript is happy importing stylesheets and images. It covers `.css`, `.scss`, `.sass`, `.less`, `.styl` (and friends), plus image formats (`.svg`, `.png`, `.jpg`, `.webp`, and so on), which import as a URL string:
+```tsx
+import logoUrl from './logo.svg';   // logoUrl is a string (a hashed URL)
+<img src={logoUrl} alt="Logo" />
+```
+For images specifically, prefer the `Toil.Image` component and its `?toil` import, which also handle layout shift and blur placeholders (see [Images](./images.md)).
+## Gotchas
+- **Global CSS is global.** A plain `.css` import puts its class names in one shared namespace. If two files both define `.button`, the last one loaded wins. Use `*.module.css` (CSS Modules) or unique prefixes to scope styles.
+- **Do not hand-edit `toil-env.d.ts`.** It is generated. If a new file type is not recognized, re-run the build so it regenerates, rather than editing it.
+- **Preprocessor packages are managed by `configure`.** Add or switch preprocessors through `toiljs configure` so the packages and imports stay in sync; do not install them by hand.
+## Related
+- [Images](./images.md): the `Toil.Image` component and image imports.
+- [The CLI](../cli/README.md): `toiljs configure` and every flag.
+- [Frontend overview](./README.md): where styles fit in the `client/` folder.

package/docs/getting-started/README.md ADDED Viewed

@@ -0,0 +1,81 @@
+# Getting started
+toiljs is a full-stack web framework: you write a React frontend and a TypeScript backend in one project, and toiljs ships both together. This section takes you from "nothing installed" to "a small feature running end to end."
+## What toiljs is
+Think of a normal web app as two programs that have to agree with each other:
+- A **frontend**: the React code that runs in your user's browser.
+- A **backend**: the code that runs on a server, answers requests, and talks to a database.
+Normally these live in separate projects, speak to each other over hand-written HTTP calls, and drift apart until something breaks at runtime. toiljs puts both in one repository and wires them together with types, so a change on one side shows up as a compile error on the other side instead of a bug in production.
+The twist is what your backend becomes. You write it in TypeScript, but toiljs does not run it in Node.js. Instead, a compiler called **toilscript** turns your backend into **WebAssembly** (often shortened to "Wasm"): a small, fast, sandboxed program that runs at the **edge**. "Edge" just means servers spread all over the world, close to your users, so requests do not have to travel to one far-away data center. A worldwide database called **ToilDB** is built in, so you can store and read data without setting up or connecting to a database yourself.
+New terms, defined once:
+- **WebAssembly / Wasm**: a compact binary format that runs code in a locked-down sandbox at near-native speed. Your backend compiles to a single `.wasm` file.
+- **toilscript**: the compiler that turns your TypeScript backend into that `.wasm` file. It accepts a strict subset of TypeScript (more on that below).
+- **Dacely edge**: the global network of servers that runs your `.wasm` backend.
+- **ToilDB**: the built-in database that lives on the edge next to your code.
+## The client / server / shared mental model
+Every toiljs project is organized into three folders. The most important thing to learn first is **where each piece of code actually runs**.
+```mermaid
+flowchart LR
+    A["Your project<br/>(one repo)"] -->|toiljs build| B["client bundle<br/>React + JS"]
+    A -->|toilscript compiles| C["server.wasm<br/>your backend"]
+    B --> U["User's browser"]
+    C --> E["Dacely edge<br/>(worldwide servers)"]
+    E --> D[("ToilDB<br/>global database")]
+    U <-->|"HTTP / realtime"| E
+```
+- **`client/`** is your React app: pages, components, and styles. It is bundled by [Vite](https://vitejs.dev) and runs **in the browser**.
+- **`server/`** is your backend: HTTP routes, database access, auth. It is compiled by toilscript to `build/server/release.wasm` and runs **on the edge** (and locally when you run the dev server).
+- **`shared/`** holds a file that toiljs **generates for you** (`shared/server.ts`). It is a fully typed client: the browser calls your backend through a `Server` object, and TypeScript checks every call. You do not write this file by hand.
+Here is the loop in one picture:
+```mermaid
+flowchart TD
+    W["client/routes/page.tsx<br/>(browser)"] -->|"Server.REST.likes.like()"| G["shared/server.ts<br/>(generated typed client)"]
+    G -->|"HTTP request"| S["server/routes/Likes.ts<br/>(your @rest route, in wasm)"]
+    S -->|"read / write"| DB[("ToilDB")]
+    S -->|"typed response"| W
+```
+You write both ends in TypeScript, and the generated `shared/server.ts` in the middle keeps them in sync.
+## Two rules to keep in mind
+These two facts explain most of how toiljs backends behave. They are covered in depth later, but it helps to meet them now.
+1. **The server runs one fresh instance per request.** Every request gets a brand-new copy of your `.wasm`, and its memory is wiped when the request ends. So a normal variable you set in one request is gone by the next request. Anything that must survive (accounts, counters, posts) has to go into **ToilDB** or another store. Nothing in a plain module-level variable persists.
+2. **The server is not Node.js.** toilscript compiles a strict subset of TypeScript, so you cannot `import` an arbitrary npm package into `server/` or use Node APIs like `fs`. Instead, toiljs gives you built-in globals for the common needs: `crypto`, cookies, email, the database, and more. See [Types](../concepts/types.md) and [Decorators](../concepts/decorators.md) for the details.
+The client side, by contrast, is normal React. You can use React libraries and browser APIs there as usual.
+## The getting-started path
+Work through these pages in order:
+1. **[Installation](./installation.md)**: check your Node.js version and install the toiljs command-line tool.
+2. **[Create a project](./create-project.md)**: scaffold a new app and see what you get.
+3. **[Project structure](./project-structure.md)**: a tour of every folder and file, and where each one runs.
+4. **[Your first app](./first-app.md)**: build a tiny feature end to end, a page that calls a backend route and reads and writes one piece of ToilDB data.
+5. **[Migrating an existing app](./migrating.md)**: bring a React app you already have into toiljs.
+6. **[Deploy](./deploy.md)**: build for production and self-host it, and how the managed edge fits in.
+## Related
+- [Documentation home](../README.md)
+- [The CLI reference](../cli/README.md)
+- [Frontend overview](../frontend/README.md)
+- [Backend overview](../backend/README.md)
+- [Database overview](../database/README.md)
+- [Compute tiers (where code runs)](../concepts/tiers.md)

package/docs/getting-started/create-project.md ADDED Viewed

@@ -0,0 +1,131 @@
+# Create a project
+Scaffold a brand-new toiljs app with one command. The CLI asks a few questions, writes the files, and (optionally) installs dependencies for you.
+## Why and when
+`toiljs create` is how every project starts. It wires up the enforced toiljs presets (TypeScript, ESLint, and Prettier config), the file-based routing, and a working client and server, so you get a project that builds and runs on the first try. Use it for a new app. To bring an **existing** React app into toiljs instead, see [Migrating](./migrating.md).
+## The command
+```sh
+toiljs create my-app
+```
+Replace `my-app` with your project name (it becomes the folder name). If you leave the name off, the wizard asks for one.
+By default this runs an interactive wizard. To skip every question and accept the defaults (handy for scripts and CI), add `--yes`:
+```sh
+toiljs create my-app --yes
+```
+## What the wizard asks
+Running `toiljs create` walks you through these prompts. Each one has a flag you can pass instead, so you can answer some or all of them up front.
+| Prompt | What it decides | Flag | Default |
+| --- | --- | --- | --- |
+| Project name | The folder and package name | (the first argument) | `my-toil-app` |
+| Which template? | How much starter code you get | `-t, --template <app\|minimal>` | `app` |
+| Styling | The CSS flavor for `client/` | `--style <css\|sass\|less\|stylus>` | `css` |
+| Add Tailwind CSS? | Adds Tailwind on top of the styling | `--tailwind` / `--no-tailwind` | off |
+| AI assistant files | Editor hint files for Claude, Cursor, Codex, Copilot | `--no-ai` (to skip) | all |
+| Optimize images at build time? | Resize and compress imported images | `--images` / `--no-images` | on |
+| Initialize a git repository? | Runs `git init` and stages the files | `--git` / `--no-git` | on |
+| Install dependencies now? | Runs your package manager's install | `--install` / `--no-install` | on |
+Two more flags do not have a prompt:
+- `--pm <npm\|pnpm\|yarn\|bun>` picks the package manager to install with (default `npm`).
+- `-y, --yes` accepts every default and runs without any prompts.
+### The two templates
+- **`app`** (default) is the full starter: a landing page, a shared layout, styles, and a set of demo routes that show off HTTP routes, typed RPC, cookies, auth, and a ToilDB-backed guestbook. Great for learning by reading real, working code.
+- **`minimal`** is the bare minimum: a layout, a single home page, and a tiny server handler with one example endpoint. Great when you want a clean slate.
+A fully non-interactive example:
+```sh
+toiljs create my-app --yes --template minimal --style css --no-tailwind --pm pnpm
+```
+## What gets scaffolded
+Here is the shape of a new **`app`** project. The exact set of demo routes may grow over time, so this is trimmed for readability.
+```text
+my-app/
+  package.json            scripts + dependencies (toiljs, react, toilscript, ...)
+  toil.config.ts          client/build config (SEO, images, page transitions)
+  toilconfig.json         server (wasm) build config for toilscript
+  tsconfig.json           TypeScript config for the client
+  eslint.config.js        linting preset
+  .prettierrc             formatting preset
+  .gitignore              ignores build output, generated files, and .env files
+  toil-env.d.ts           generated editor types for client globals (Toil.*)
+  toil-routes.d.ts        generated typed-route names (filled in on first build)
+  README.md
+  CLAUDE.md / AGENTS.md   AI assistant hint files (if you kept them)
+  client/                 your React app (runs in the browser)
+    toil.tsx              the client entry: mounts routes + layout
+    layout.tsx            the root layout that wraps every page
+    404.tsx               the not-found page
+    global-error.tsx      the top-level error page
+    routes/               file-based pages (index.tsx = "/", about.tsx = "/about", ...)
+    components/           shared React components
+    styles/main.css       global styles
+    public/               static files served as-is (favicon, robots.txt, images)
+  server/                 your backend (compiled to wasm, runs on the edge)
+    main.ts               the entry: wires the handler + imports your surface modules
+    tsconfig.json         server-only TS config (loads the toilscript editor plugin)
+    toil-server-env.d.ts  generated editor types for server globals (Cookie, crypto, ...)
+    core/                 your top-level request handler and shared logic
+    models/               @data classes (the typed wire types)
+    routes/               @rest controllers (HTTP endpoints)
+    services/             @service classes and @remote functions (typed RPC)
+    migrations/           ToilDB schema migrations (README explains the convention)
+    scheduled/            reserved for scheduled tasks
+  shared/                 (created by the build)
+    server.ts             GENERATED typed client: the Server proxy + @data codecs
+```
+The **`minimal`** template is the same layout with far fewer files: `client/` has just `layout.tsx`, `routes/index.tsx`, and `styles/main.css`; `server/` has `main.ts` and `core/AppHandler.ts` with a single example endpoint.
+A few files are worth calling out now, and the next page ([Project structure](./project-structure.md)) walks through all of them:
+- **`shared/server.ts` does not exist yet** in a fresh project. It is generated the first time you run `toiljs dev` or `toiljs build`. That is normal and expected.
+- **`toil-routes.d.ts`** starts as a stub and gets filled in with your real route names on the first build, which is what makes `Toil.Link` route names type-check.
+- **`.env` and `.env.secrets` are not created** for you. You add them yourself when you need local environment variables or secrets. They are already listed in `.gitignore` so you never commit them. See [Environment and secrets](../services/environment.md).
+## Run it
+Once scaffolding (and install) finishes, the CLI prints your next steps:
+```sh
+cd my-app
+npm run dev
+```
+`npm run dev` runs `toiljs dev`, which builds your server to wasm, generates `shared/server.ts`, and starts the dev server with hot reload. Open the printed URL (by default `http://localhost:3000`) and you have a live app.
+If you told the wizard **not** to install dependencies, run `npm install` first.
+## Gotchas and notes
+- **Scaffolding into a non-empty folder** asks for confirmation in interactive mode, and fails in `--yes` mode. Create into a fresh, empty directory.
+- **The project name must be a valid package name** and must stay inside the current directory (no `..`, no absolute paths).
+- **Git init is best-effort.** If `git` is not installed, the CLI skips that step and keeps going.
+- **You do not run `toilscript` yourself.** It is added as a dependency and driven by `toiljs dev` / `toiljs build`.
+## Related
+- [Project structure](./project-structure.md)
+- [Your first app](./first-app.md)
+- [The CLI reference](../cli/README.md)
+- [Configuration](../concepts/config.md)
+- [Styling](../frontend/styling.md)