@remix-run/cli 0.1.0 → 0.3.0

package/template/.agents/skills/remix/references/data-and-validation.md

@@ -0,0 +1,379 @@
+# Data Access and Validation
+
+## What This Covers
+
+How input becomes a value the app trusts, and how that value reaches storage. Read this when the
+task involves:
+
+- Defining database tables, columns, relations, and migrations
+- Querying or mutating persisted data with `Database`
+- Parsing and validating user input from forms, query strings, or external payloads
+- Choosing between schema-level checks, table validation hooks, and migration-level constraints
+
+For where validation runs in the request lifecycle, see `routing-and-controllers.md`. For session
+or identity-bound writes, see `auth-and-sessions.md`.
+
+## Table Definitions (`remix/data-table`)
+
+Define tables with typed columns, relations, and optional validation hooks:
+
+```typescript
+import { belongsTo, column as c, hasMany, table } from 'remix/data-table'
+import type { TableRow, TableRowWith } from 'remix/data-table'
+
+export const books = table({
+  name: 'books',
+  columns: {
+    id: c.integer().primaryKey().autoIncrement(),
+    slug: c.text().notNull().unique(),
+    title: c.text().notNull(),
+    author: c.text().notNull(),
+    price: c.decimal(10, 2).notNull(),
+    genre: c.text().notNull(),
+    in_stock: c.boolean(),
+  },
+})
+
+export const orders = table({
+  name: 'orders',
+  columns: {
+    id: c.integer().primaryKey().autoIncrement(),
+    user_id: c.integer().notNull().references('users', 'id'),
+    total: c.decimal(10, 2).notNull(),
+    created_at: c.integer().notNull(),
+  },
+  relations: {
+    user: belongsTo('users', 'user_id'),
+    items: hasMany('order_items', 'order_id'),
+  },
+})
+
+export type Book = TableRow<typeof books>
+export type Order = TableRow<typeof orders>
+export type OrderWithItems = TableRowWith<typeof orders, 'items'>
+```
+
+### Column types
+
+| Method                        | SQL type           |
+| ----------------------------- | ------------------ |
+| `c.integer()`                 | INTEGER            |
+| `c.text()`                    | TEXT               |
+| `c.boolean()`                 | BOOLEAN            |
+| `c.decimal(precision, scale)` | DECIMAL            |
+| `c.enum([...])`               | TEXT (string enum) |
+| `c.uuid()`                    | UUID / TEXT        |
+| `c.varchar(length)`           | VARCHAR            |
+
+Column modifiers: `.primaryKey()`, `.autoIncrement()`, `.notNull()`, `.unique()`,
+`.references(table, column, fkName?)`, `.onDelete(action)`, `.default(value)`.
+
+Composite primary keys go on the table option, not the column: `primaryKey: ['order_id', 'book_id']`.
+
+### Schema vs migrations
+
+Column modifiers describe SQL constraints — the source of truth for them is your **migration**
+files, where they generate the actual DDL. Runtime `table(...)` definitions in `app/data/schema.ts`
+can use the same modifiers, or they can stay minimal (`c.integer()`, `c.text()`, ...) since the
+runtime only needs the column shape and validation hooks. Two valid patterns:
+
+- **Modifiers in both** — schema and migrations stay in sync visually; useful when you want
+  schema-level docs.
+- **Bare columns in schema, full modifiers in migrations** — schema describes what the app reads
+  and writes; migrations own the DDL and constraints.
+
+Pick one and apply it consistently across the app.
+
+### Table lifecycle hooks
+
+Tables can define validation and lifecycle hooks:
+
+- `validate` runs before `create` and `update` writes and should return either `{ value }` or
+  `{ issues }`
+- `beforeWrite` can normalize or veto `create`/`update` values
+- `afterWrite` observes completed `create`/`update` operations
+- `beforeDelete` and `afterDelete` observe or veto deletes
+- `afterRead` can normalize or reject row values after reads
+
+```typescript
+export const books = table({
+  name: 'books',
+  columns: {
+    /* ... */
+  },
+  beforeWrite({ value }) {
+    if (typeof value.slug === 'string') {
+      return { value: { ...value, slug: value.slug.trim().toLowerCase() } }
+    }
+    return { value }
+  },
+  validate({ operation, value }) {
+    let issues = []
+    if (operation === 'create' && !value.slug) {
+      issues.push({ message: 'Slug is required.', path: ['slug'] })
+    }
+    return issues.length > 0 ? { issues } : { value }
+  },
+  afterRead({ value }) {
+    return { value }
+  },
+})
+```
+
+## Database Setup
+
+Create a database with an adapter and expose it via middleware:
+
+```typescript
+import BetterSqlite3 from 'better-sqlite3'
+import { createDatabase, Database } from 'remix/data-table'
+import { createSqliteDatabaseAdapter } from 'remix/data-table/sqlite'
+
+let sqlite = new BetterSqlite3('./db/app.db')
+sqlite.pragma('foreign_keys = ON')
+let adapter = createSqliteDatabaseAdapter(sqlite)
+export let db = createDatabase(adapter)
+```
+
+`createSqliteDatabaseAdapter` accepts synchronous SQLite clients with a shared `prepare`/`exec`
+surface, including Node's `node:sqlite`, Bun's `bun:sqlite`, and compatible clients. Use whichever
+client fits the runtime instead of assuming `better-sqlite3` is required.
+
+### Database middleware
+
+```typescript
+import type { Middleware } from 'remix/router'
+import { Database } from 'remix/data-table'
+
+export function loadDatabase(): Middleware {
+  return async (context, next) => {
+    context.set(Database, db)
+    return next()
+  }
+}
+```
+
+### Querying
+
+```typescript
+let db = get(Database)
+
+// Find by primary key
+let book = await db.find(books, id)
+
+// Find one by condition
+let user = await db.findOne(users, { where: { email } })
+
+// Find many with ordering
+let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })
+
+// Count
+let total = await db.count(orders, { where: { user_id: userId } })
+
+// Query builder
+let genres = await db.query(books).select('genre').distinct().orderBy('genre', 'asc').all()
+
+// Create
+let newBook = await db.create(books, { slug: 'new-book', title: 'New Book' /* ... */ })
+
+// Update
+await db.update(books, bookId, { title: 'Updated Title' })
+
+// Delete
+await db.delete(books, bookId)
+```
+
+### Operators
+
+```typescript
+import { inList } from 'remix/data-table/operators'
+
+let featured = await db.findMany(books, {
+  where: inList('slug', ['book-a', 'book-b', 'book-c']),
+})
+```
+
+## Migrations
+
+### Writing migrations
+
+```typescript
+import { column as c, createMigration } from 'remix/data-table/migrations'
+import { table } from 'remix/data-table'
+
+export default createMigration({
+  async up({ schema }) {
+    let users = table({
+      name: 'users',
+      columns: {
+        id: c.integer().primaryKey().autoIncrement(),
+        email: c.text().notNull().unique(),
+        name: c.text().notNull(),
+      },
+    })
+    await schema.createTable(users)
+    await schema.createIndex(users, 'email', { name: 'users_email_idx', unique: true })
+  },
+
+  async down({ schema }) {
+    await schema.dropTable('users')
+  },
+})
+```
+
+Migrations can also import table definitions from the app schema to avoid duplication:
+
+```typescript
+import { createMigration } from 'remix/data-table/migrations'
+import { users, authAccounts } from '../../app/data/schema.ts'
+
+export default createMigration({
+  async up({ schema }) {
+    await schema.createTable(users)
+    await schema.createTable(authAccounts)
+  },
+})
+```
+
+### Running migrations
+
+```typescript
+import { createMigrationRunner } from 'remix/data-table/migrations'
+import { loadMigrations } from 'remix/data-table/migrations/node'
+
+let migrations = await loadMigrations('./db/migrations')
+let runner = createMigrationRunner(adapter, migrations)
+await runner.up()
+```
+
+### Migration file naming
+
+Name migration files with a timestamp prefix: `20260228090000_create_users.ts`. Place them in
+`db/migrations/`.
+
+## Input Validation (`remix/data-schema`)
+
+Use `data-schema` to validate user input (forms, query params, API payloads). This is separate from
+table-level `validate` hooks which run at persistence.
+
+### Schema builders
+
+```typescript
+import * as s from 'remix/data-schema'
+import { email, minLength, maxLength } from 'remix/data-schema/checks'
+
+let userSchema = s.object({
+  name: s.string().pipe(minLength(1)),
+  email: s.string().pipe(email()),
+  age: s.optional(s.number()),
+})
+
+let result = s.parse(userSchema, data)
+```
+
+### FormData validation
+
+Use `remix/data-schema/form-data` to validate `FormData` directly:
+
+```typescript
+import * as s from 'remix/data-schema'
+import * as f from 'remix/data-schema/form-data'
+import { email, minLength } from 'remix/data-schema/checks'
+
+let signupSchema = f.object({
+  name: f.field(s.string().pipe(minLength(1))),
+  email: f.field(s.string().pipe(email())),
+  password: f.field(s.string().pipe(minLength(8))),
+})
+
+// In a controller action:
+let formData = get(FormData)
+let { name, email, password } = s.parse(signupSchema, formData)
+```
+
+### Reading FormData: middleware vs `request.formData()`
+
+There are two ways to get a `FormData` value inside an action.
+
+The recommended way: register `formData()` middleware in the root stack and read with
+`get(FormData)`. The body is parsed once per request, and the typed `FormData` value flows through
+the context system. This also lets `methodOverride()` and CSRF middleware work uniformly.
+
+```typescript
+import { formData } from 'remix/middleware/form-data'
+
+let router = createRouter({
+  middleware: [, /* ... */ formData() /* ... */],
+})
+
+// In an action:
+let parsed = s.parseSafe(signupSchema, get(FormData))
+```
+
+The fallback: `await request.formData()` directly. This works without middleware and is fine for
+small one-off cases, but it bypasses the context system, runs once per call site, and doesn't
+compose with middleware that depends on parsed form fields.
+
+### Safe parsing
+
+`s.parse` throws on invalid input. `s.parseSafe` returns a tagged result and is usually what an
+action wants, since validation failure is an expected outcome (re-render the form with errors)
+rather than an exception:
+
+```typescript
+let result = s.parseSafe(signupSchema, get(FormData))
+if (!result.success) {
+  return render(<SignupPage errors={result.issues} />, { status: 400 })
+}
+let { name, email, password } = result.value
+```
+
+Returning a `Response` for validation failures keeps the route contract honest: the same action
+returns 200 on success, 400 with errors on bad input, no out-of-band exception flow.
+
+### Transforming validated output
+
+Use `.transform(...)` when a schema should validate one shape but return another value or output
+type. Transforms run after validation and compose with `.pipe(...)` and `.refine(...)`:
+
+```typescript
+import * as coerce from 'remix/data-schema/coerce'
+
+let slugSchema = s
+  .string()
+  .pipe(minLength(1))
+  .transform((value) => value.trim().toLowerCase().replace(/\s+/g, '-'))
+
+let pageSchema = f.object({
+  page: f.field(s.defaulted(coerce.coerceNumber(), 1).refine(Number.isInteger)),
+  q: f.field(s.defaulted(s.string(), '').transform((value) => value.trim())),
+})
+
+let { page, q } = s.parse(pageSchema, formData)
+```
+
+### Anti-patterns
+
+Avoid these shapes when reading and validating input:
+
+- **Raw `formData.get('name')` plus an `if (typeof name !== 'string')` guard**, then a thrown
+  custom error. This reinvents what `data-schema` already does, loses the typed result, and
+  pushes error translation into a `try/catch` instead of a return value.
+- **Letting route-local domain errors leak out of the action.** Translate expected outcomes (bad
+  input, missing record, duplicate entry) into the `Response` the route means to return instead of
+  throwing a custom `Error` subclass with a `status` field and catching it later.
+- **Trusting `params`, query strings, or external payloads without a schema.** Anything that
+  crosses a trust boundary should be parsed before it reaches business logic.
+
+### Common patterns
+
+```typescript
+// Optional with default
+let limitSchema = f.field(s.defaulted(s.string(), '10'))
+
+// Union types
+let methodSchema = s.union([s.literal('credentials'), s.literal('google'), s.literal('github')])
+
+// Refinements
+let idSchema = s.number().refine(Number.isInteger, 'Expected an integer')
+```

package/template/.agents/skills/remix/references/hydration-frames-navigation.md

@@ -0,0 +1,297 @@
+# Hydration, Frames, and Navigation
+
+## What This Covers
+
+How server-rendered UI becomes interactive in the browser, and how the page updates without a full
+navigation. Read this when the task involves:
+
+- Marking a component for client-side hydration with `clientEntry`
+- Booting the client runtime with `run`
+- Streaming server content into a region of the page with `<Frame>` and reloading those regions
+- Triggering Navigation API transitions with `navigate(...)` or `link(...)`
+- Server rendering with `renderToStream` or `renderToString`
+- Managing the document `<head>`
+
+For component-local state and updates, see `component-model.md`. For host-element behavior and
+events, see `mixins-styling-events.md`.
+
+## Server First, Then Hydrate
+
+Make the server route correct before adding `clientEntry(...)`. A POST should already do the right
+thing on its own — return HTML, a redirect, or an error response — and a GET should already render
+the page the user expects. `clientEntry` exists to layer interactivity on top of UI that already
+works without it.
+
+When server state changes after a mutation, prefer reloading a `<Frame>` when the UI region already
+maps cleanly to a server-rendered route. Frames re-fetch the same route, so the rendering logic
+stays in one place and the client does not need a parallel "state" API.
+
+```tsx
+on('submit', async (event, signal) => {
+  event.preventDefault()
+  await fetch(routes.cart.add.href(), {
+    method: 'POST',
+    body: new FormData(event.currentTarget),
+    signal,
+  })
+  if (signal.aborted) return
+  await handle.frames.get('cart-summary')?.reload()
+})
+```
+
+Use polling or a small JSON state endpoint when the data changes outside this page, or when a tiny
+shared widget would be heavier to model as a frame. Pick the lightest sync mechanism that preserves
+clear ownership of rendering logic.
+
+## Client Entries
+
+Use `clientEntry` to mark a component for client-side hydration. In source-served apps, prefer the
+source module's `import.meta.url` as the entry ID and let server rendering map it to the public
+asset URL:
+
+```tsx
+import { clientEntry, on, type Handle } from 'remix/ui'
+
+export const Counter = clientEntry(
+  import.meta.url,
+  function Counter(handle: Handle<{ initialCount: number; label: string }>) {
+    let count = handle.props.initialCount
+
+    return () => (
+      <div>
+        <span>
+          {handle.props.label}: {count}
+        </span>
+        <button
+          mix={on('click', () => {
+            count++
+            handle.update()
+          })}
+        >
+          +
+        </button>
+      </div>
+    )
+  },
+)
+```
+
+On the server, provide `resolveClientEntry` to `renderToStream(...)` so source file URLs become
+browser-loadable asset URLs. Keep this resolution in the render helper so component modules do not
+hard-code deployment-specific asset paths:
+
+```tsx
+let stream = renderToStream(<App />, {
+  async resolveClientEntry(entryId, component) {
+    let exportName = entryId.split('#')[1] || component.name
+    if (!exportName) {
+      throw new Error(`Unable to resolve client entry export for ${entryId}`)
+    }
+
+    return {
+      href: await assetServer.getHref(entryId),
+      exportName,
+    }
+  },
+})
+```
+
+If the module export name differs from the component function name, include `#ExportName` in the
+entry ID or return the exact export name from `resolveClientEntry`. A render helper that only
+supports source-owned entries can also fail fast when `entryId` is not a `file://` URL.
+
+On the server, `clientEntry` components render like any other component. The server wraps their
+output in comment markers and serializes props into a `<script type="application/json">` tag.
+
+Client entry props must be serializable: strings, numbers, booleans, `null`, `undefined`, plain
+objects/arrays of the above, JSX elements, and `<Frame>` elements. Functions and class instances
+cannot be passed.
+
+## Booting the Client
+
+Use `run` to start the client runtime. It scans the document for client entry markers, loads
+modules, and hydrates each one:
+
+```tsx
+import { run } from 'remix/ui'
+
+let app = run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+  async resolveFrame(src, signal, target) {
+    let headers = new Headers({ accept: 'text/html' })
+    if (target) headers.set('x-remix-target', target)
+    let response = await fetch(src, { headers, signal })
+    return response.body ?? (await response.text())
+  },
+})
+
+app.addEventListener('error', (event) => {
+  console.error('Component error:', event.error)
+})
+
+await app.ready()
+```
+
+### `run` options
+
+- **`loadModule(moduleUrl, exportName)`** (required) — return the component function for each
+  client entry. Typically uses dynamic `import()`.
+- **`resolveFrame(src, signal, target)`** (optional) — called when a `<Frame>` loads or reloads
+  content. `target` is available when frame targeting matters.
+
+### `app` methods
+
+- **`app.ready()`** — resolves when all initial client entries are hydrated
+- **`app.flush()`** — synchronously flushes all pending updates
+- **`app.dispose()`** — tears down all hydrated components
+
+`app` is an `EventTarget` that emits `error` events from any hydrated component.
+
+## Frames
+
+A `<Frame>` renders server content into the page. Frames stream after the initial HTML, nest inside
+other frames, contain client entries, and can be reloaded without full page navigation.
+
+```tsx
+import { Frame } from 'remix/ui'
+
+function App() {
+  return () => (
+    <div>
+      <Frame src="/sidebar" fallback={<div>Loading...</div>} />
+      <Frame name="main" src="/main-content" />
+    </div>
+  )
+}
+```
+
+### Frame props
+
+- **`src`** (required) — URL to fetch the frame content from
+- **`fallback`** (optional) — content to show while loading; determines streaming behavior
+- **`name`** (optional) — registers the frame for lookup via `handle.frames.get(name)`
+- **`on`** (optional) — event handlers for events dispatched from the frame element
+
+### Blocking vs non-blocking
+
+- **Without `fallback`** (blocking) — the server waits for frame content before sending the initial
+  HTML chunk
+- **With `fallback`** (non-blocking) — the fallback renders immediately; real content streams in
+  later and replaces it
+
+### Reloading frames
+
+Client entries inside a frame can trigger a reload:
+
+```tsx
+// Reload the containing frame
+handle.frame.reload()
+
+// Reload an adjacent named frame
+await handle.frames.get('cart-summary')?.reload()
+
+// Reload the entire page/frame tree
+handle.frames.top.reload()
+```
+
+When a frame reloads, matching DOM nodes are updated in place. Client entries receive updated props
+while preserving their local component state.
+
+### Nested frames
+
+Frames can nest. Each frame owns its own DOM region and hydrates client entries independently.
+During SSR, `handle.frame.src` points at the frame being rendered, while
+`handle.frames.top.src` stays fixed at the outer document URL.
+
+## Server Rendering
+
+### `renderToStream`
+
+Renders a component tree to a `ReadableStream<Uint8Array>`. Sends initial HTML immediately and
+streams frame content as it resolves:
+
+```tsx
+import { renderToStream } from 'remix/ui/server'
+
+let stream = renderToStream(<App />, {
+  frameSrc: request.url,
+  resolveFrame(src, target, context) {
+    let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
+    return fetchHtml(frameUrl)
+  },
+  onError(error) {
+    console.error(error)
+  },
+})
+
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/html; charset=utf-8' },
+})
+```
+
+Options:
+
+- **`frameSrc`** — seeds SSR frame state; populates `handle.frame.src` and `handle.frames.top.src`
+- **`topFrameSrc`** — overrides the root frame URL for nested frame renders (carry forward from
+  `resolveFrame` context)
+- **`resolveFrame(src, target, context)`** — return HTML string, `ReadableStream<Uint8Array>`, or a
+  promise of either. `context.currentFrameSrc` is the containing frame URL; `context.topFrameSrc`
+  is the outer document URL
+- **`onError(error)`** — called on rendering errors
+
+### `renderToString`
+
+Renders a component tree to a complete HTML string. Use for static pages or embedding HTML:
+
+```tsx
+import { renderToString } from 'remix/ui/server'
+let html = await renderToString(<App />)
+```
+
+### CSS in SSR
+
+Components using the `css` mixin have styles collected during rendering and emitted as a single
+`<style>` tag in `<head>`. No client-side style injection needed.
+
+## Navigation
+
+Use real anchors for normal document navigation. For app-driven navigation:
+
+- `navigate(href, options?)` — performs a Navigation API transition
+- `link(href, options?)` mixin — makes any element behave like a navigation link
+
+```tsx
+import { navigate } from 'remix/ui'
+navigate('/dashboard', { history: 'replace' })
+```
+
+Options: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
+
+Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-document`.
+
+## Head Management
+
+Manage document head with an explicit `<head>` in your document structure:
+
+```tsx
+function App() {
+  return () => (
+    <html>
+      <head>
+        <title>Dashboard</title>
+        <meta name="description" content="Team dashboard" />
+        <link rel="stylesheet" href="/styles/app.css" />
+      </head>
+      <body>
+        <main>...</main>
+      </body>
+    </html>
+  )
+}
+```
+
+Put `title`, `meta`, `link`, and `style` tags inside an explicit `<head>`. Bare head-like tags
+rendered outside `<head>` stay where they are — they are not moved into the document head for you.