@remix-run/cli 0.1.0 → 0.3.0

package/template/.agents/skills/remix/references/routing-and-controllers.md

@@ -0,0 +1,391 @@
+# Routing and Controllers
+
+## What This Covers
+
+Patterns for declaring URLs, handling requests, and wiring routes to controllers. Read this when
+the task involves:
+
+- Defining or changing the URL surface of the app
+- Writing or reorganizing controllers and actions
+- Reading request data (`params`, `url`, `request`, context values)
+- Returning a `Response` for HTML, redirects, JSON, or errors
+- Generating internal URLs with `.href()`
+
+The companion reference for shaping `Request` bodies, validating input, and dealing with persisted
+data is `data-and-validation.md`. For request lifecycle and middleware ordering, see
+`middleware-and-server.md`.
+
+## Route Builders
+
+Import all route builders from `remix/routes`.
+
+### `route(prefix, map)` — nested route group
+
+Adds a URL prefix to all children. Can also be called as `route(map)` without a prefix for a
+top-level grouping. Inside `route(...)`, a nested map may be either a `route('prefix', { ... })`
+call (when you want a shared URL prefix) or a plain object literal (when each leaf already owns
+its absolute path).
+
+```typescript
+import { route, get, post } from 'remix/routes'
+
+export const routes = route({
+  home: '/',
+
+  // Plain object — no shared prefix, each leaf has an absolute path.
+  books: {
+    index: '/books',
+    show: '/books/:slug',
+  },
+
+  // route('auth', ...) — every leaf is prefixed with /auth.
+  auth: route('auth', {
+    login: get('login'),
+    logout: post('logout'),
+  }),
+})
+```
+
+### Leaf route builders
+
+| Builder        | HTTP method | Example              |
+| -------------- | ----------- | -------------------- |
+| `get(path)`    | GET         | `get('/search')`     |
+| `post(path)`   | POST        | `post('/logout')`    |
+| `put(path)`    | PUT         | `put('/api/update')` |
+| `del(path)`    | DELETE      | `del('/api/remove')` |
+| String literal | ANY         | `'/about'`           |
+
+### `form(path, options?)` — form route
+
+Creates a GET + POST pair for HTML form workflows. Expands to an `index` (GET) and an `action`
+(POST) by default.
+
+```typescript
+contact: form('contact')
+// Produces routes.contact.index (GET /contact) and routes.contact.action (POST /contact)
+
+settings: form('settings', { formMethod: 'PUT', names: { action: 'update' } })
+// Produces routes.settings.index (GET) and routes.settings.update (PUT)
+```
+
+### `resources(name, options?)` — REST resources
+
+Expands to conventional CRUD routes: `index`, `new`, `create`, `show`, `edit`, `update`, `destroy`.
+
+```typescript
+books: resources('books', { param: 'bookId' })
+// GET /books, GET /books/new, POST /books, GET /books/:bookId, ...
+
+orders: resources('orders', { only: ['index', 'show'], param: 'orderId' })
+// GET /orders, GET /orders/:orderId
+```
+
+### URL generation with `.href()`
+
+Route objects expose `.href()` for type-safe URL generation:
+
+```typescript
+redirect(routes.home.href())
+redirect(routes.account.orders.show.href({ orderId: '42' }))
+```
+
+## Actions
+
+An action is the handler for one leaf route. In Remix app code, actions should live in controllers.
+Use `Action` only when a reusable helper needs to type one action before it is added to a
+controller or when you are doing low-level router wiring outside the `app/actions` convention:
+
+```typescript
+import { createAction } from 'remix/router'
+
+import { routes } from '../routes.ts'
+
+export const search = createAction(routes.search, {
+  async handler({ url }) {
+    let query = url.searchParams.get('q') ?? ''
+    let results = await searchIndex(query)
+    return render(<SearchPage query={query} results={results} />)
+  },
+})
+```
+
+The handler receives a context object with:
+
+- `get(key)` — read a value set by middleware (e.g. `get(Database)`, `get(Session)`, `get(Auth)`)
+- `params` — typed route params
+- `url` — the request URL
+- `request` — the raw `Request`
+
+Actions with inline middleware:
+
+```typescript
+import { requireAuth } from 'remix/middleware/auth'
+
+router.get(routes.account.index, {
+  middleware: [requireAuth()],
+  handler: accountAction.handler,
+})
+```
+
+## Returning Responses
+
+An action returns a `Response`. The shape of that response is part of the route contract, and
+choosing it well saves a lot of glue elsewhere.
+
+### Render HTML
+
+For pages, render a component tree and return the resulting `Response`:
+
+```typescript
+async handler({ get }) {
+  let db = get(Database)
+  let books = await db.findMany(books, { orderBy: ['id', 'asc'] })
+  return render(<IndexPage books={books} />)
+}
+```
+
+### Redirect after a mutation
+
+For state-changing routes (POST, PUT, PATCH, DELETE), the canonical reply is a redirect to the
+resulting page. Pass `303` explicitly when you want a POST-redirect-GET flow:
+
+```typescript
+import { redirect } from 'remix/response/redirect'
+
+async create({ get }) {
+  let formData = get(FormData)
+  let parsed = s.parseSafe(bookSchema, formData)
+  if (!parsed.success) {
+    return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
+  }
+
+  let db = get(Database)
+  let book = await db.create(books, parsed.value)
+
+  return redirect(routes.books.show.href({ slug: book.slug }), 303)
+}
+```
+
+This pattern works without JavaScript and stays compatible with `clientEntry(...)` enhancements
+on top.
+
+### Return an error response
+
+For expected failures — validation, conflict, not found — return a `Response` directly. Reserve
+thrown errors for genuinely unexpected failures.
+
+```typescript
+async show({ get, params }) {
+  let db = get(Database)
+  let book = await db.find(books, params.bookId)
+  if (!book) return new Response('Not Found', { status: 404 })
+  return render(<ShowPage book={book} />)
+}
+```
+
+For form re-rendering with errors, return the page component with the parsed issues:
+
+```typescript
+let formData = get(FormData)
+let parsed = s.parseSafe(signupSchema, formData)
+if (!parsed.success) {
+  return render(<SignupPage errors={parsed.issues} values={Object.fromEntries(formData)} />, {
+    status: 400,
+  })
+}
+```
+
+### Return JSON
+
+For routes consumed by client code rather than rendered as a page (autocomplete endpoints, polling
+APIs, inter-service calls), return a JSON `Response`. Use `SuperHeaders` from `remix/headers` when
+typed header accessors make the response clearer:
+
+```typescript
+import Headers from 'remix/headers'
+
+let headers = new Headers()
+headers.contentType = { mediaType: 'application/json', charset: 'utf-8' }
+headers.cacheControl = { noStore: true }
+
+return new Response(JSON.stringify({ results }), {
+  headers,
+})
+```
+
+If you find yourself returning JSON for what is really a browser form submission, prefer the
+redirect-after-POST pattern instead. JSON-only mutation endpoints make it harder to support
+non-JS clients, harder to share rendering logic, and easier for the client to drift out of sync
+with the server.
+
+## Controllers
+
+A controller owns the direct leaf routes in one route map. Each key in `actions` matches a direct
+leaf route key in the route definition passed to `router.map(...)`. Nested route-map keys do not
+belong inside a controller's `actions`; map those route maps with their own controllers.
+
+Configure `RouterTypes.context` with your app context in the router module, then use
+`createController()` so `get(Database)`, `get(Session)`, `get(Auth)`, etc. are typed against your
+middleware stack without repeating a type clause on every controller.
+
+```typescript
+import { createController } from 'remix/router'
+
+import { routes } from '../routes.ts'
+
+export default createController(routes.books, {
+  actions: {
+    async index({ get }) {
+      let db = get(Database)
+      let items = await db.findMany(books, { orderBy: ['id', 'asc'] })
+      return render(<IndexPage items={items} />)
+    },
+
+    async show({ get, params }) {
+      let db = get(Database)
+      let book = await db.find(books, params.bookId)
+      if (!book) return new Response('Not Found', { status: 404 })
+      return render(<ShowPage book={book} />)
+    },
+  },
+})
+```
+
+### Root controller
+
+The root route map uses `app/actions/controller.tsx` and owns only top-level leaf routes:
+
+```typescript
+// routes.ts
+export const routes = route({
+  assets: get('/assets/*path'),
+  home: '/',
+  account: route('account', {
+    index: '/',
+    settings: form('settings', { formMethod: 'PUT', names: { action: 'update' } }),
+  }),
+})
+
+// app/actions/controller.tsx
+export default createController(routes, {
+  actions: {
+    async assets({ request }) {
+      return (await assetServer.fetch(request)) ?? new Response('Not Found', { status: 404 })
+    },
+    home() {
+      return render(<HomePage />)
+    },
+  },
+})
+```
+
+Because `account` is a nested route map, it is not an action key in the root controller.
+
+### Nested route maps
+
+Nested route maps use their own controllers under `app/actions/<route-key>/controller.tsx`.
+Directory names under `app/actions/` are route-map keys, not URL path segments.
+
+```typescript
+// app/actions/account/controller.tsx
+export default createController(routes.account, {
+  middleware: [requireAuth()],
+  actions: {
+    index() {
+      return render(<AccountPage />)
+    },
+  },
+})
+
+// app/actions/account/settings/controller.tsx
+export default createController(routes.account.settings, {
+  middleware: [requireAuth()],
+  actions: {
+    index() {
+      return render(<SettingsPage />)
+    },
+    update() {
+      return redirect(routes.account.index.href(), 303)
+    },
+  },
+})
+```
+
+Then map each route map explicitly:
+
+```typescript
+import rootController from './actions/controller.tsx'
+import accountController from './actions/account/controller.tsx'
+import accountSettingsController from './actions/account/settings/controller.tsx'
+
+let router = createRouter({ middleware })
+
+router.map(routes, rootController)
+router.map(routes.account, accountController)
+router.map(routes.account.settings, accountSettingsController)
+```
+
+### Controller middleware
+
+The `middleware` array on a controller runs only for the direct actions in that controller, before
+action-level middleware. It does not apply to other controllers.
+
+```typescript
+export default createController(routes.admin, {
+  middleware: [requireAuth(), requireAdmin()],
+  actions: {
+    /* all actions require auth + admin */
+  },
+})
+```
+
+## Registering Routes
+
+Use `router.map` for route maps and controllers. Map each nested route map explicitly. Use verb
+methods only for low-level router wiring outside the `app/actions` controller convention.
+
+```typescript
+let router = createRouter({ middleware })
+
+// Route maps → controllers
+router.map(routes, rootController)
+router.map(routes.contact, contactController)
+router.map(routes.auth, authController)
+router.map(routes.auth.login, authLoginController)
+router.map(routes.admin, adminController)
+router.map(routes.admin.books, adminBooksController)
+
+// Leaf route → one-off action
+router.get(routes.search, searchAction)
+router.post(routes.logout, logoutAction)
+```
+
+## Typed Context
+
+Define an `AppContext` type from your middleware stack, then make it the default context used by
+`createAction()` and `createController()`:
+
+```typescript
+import type { MiddlewareContext, ContextWithParams, AnyParams } from 'remix/router'
+
+type RootMiddleware = [
+  ReturnType<typeof formData>,
+  ReturnType<typeof session>,
+  ReturnType<typeof loadDatabase>,
+  ReturnType<typeof loadAuth>,
+]
+
+export type AppContext<params extends AnyParams = {}> = ContextWithParams<
+  MiddlewareContext<RootMiddleware>,
+  params
+>
+
+declare module 'remix/router' {
+  interface RouterTypes {
+    context: AppContext
+  }
+}
+```
+
+This gives typed `context.get(Database)`, `context.get(Session)`, `context.get(Auth)`, etc.

package/template/.agents/skills/remix/references/testing-patterns.md

@@ -0,0 +1,172 @@
+# Testing
+
+## What This Covers
+
+How to test the two layers most Remix code lives in: HTTP behavior and DOM behavior. Read this when
+the task involves:
+
+- Driving the router with `router.fetch(new Request(...))` and asserting on the returned `Response`
+- Building a fresh router per test for session, storage, or database isolation
+- Rendering components into a real DOM with `render(...)` or `createRoot(...)`
+- Configuring `remix test` discovery, excludes, and coverage
+- Using adjacent CLI checks such as `remix routes`, `remix doctor`, and `remix version`
+- Choosing which layer to test for a given behavior
+
+For session and auth test setup, see `auth-and-sessions.md`. For component lifecycle, see
+`component-model.md`.
+
+## Two Shapes
+
+Remix tests run with `remix test`, use `remix/test` for the test framework, and use
+`remix/assert` for assertions. Two main shapes:
+
+- **Server / router tests** — drive the router with `router.fetch(new Request(...))` and assert
+  on the returned `Response`. No DOM, no browser harness.
+- **Component tests** — render a component into a real DOM `Element` with `render(...)`, or use
+  `createRoot(...)` directly when you need lower-level root control.
+
+## Server / Router Tests
+
+Treat the router as a pure `(Request) => Promise<Response>` function. Build a fresh app router
+per test (or per suite) so middleware state — sessions, in-memory storage, the database — stays
+isolated.
+
+```ts
+import * as assert from 'remix/assert'
+import { describe, it } from 'remix/test'
+
+import { createBookstoreRouter } from '../app/router.ts'
+import { routes } from '../app/routes.ts'
+
+describe('home', () => {
+  it('responds 200 with the home page', async () => {
+    let router = createBookstoreRouter()
+    let response = await router.fetch(new Request('http://localhost' + routes.home.href()))
+
+    assert.equal(response.status, 200)
+    assert.match(await response.text(), /Welcome to the Bookstore/)
+  })
+})
+```
+
+Use `routes.<name>.href(...)` to build URLs in tests so they stay in sync with the route
+definition. For form-style POSTs, attach a `FormData` body to the `Request`. For tests that need
+a known session, swap in `createMemorySessionStorage()` and a test cookie when constructing the
+router.
+
+```ts
+import { createMemorySessionStorage } from 'remix/session-storage/memory'
+import { createCookie } from 'remix/cookie'
+
+let router = createBookstoreRouter({
+  sessionCookie: createCookie('session', { secrets: ['test'] }),
+  sessionStorage: createMemorySessionStorage(),
+})
+```
+
+Use `createTestServer` from `remix/node-fetch-server/test` when the behavior depends on a real
+HTTP origin, redirects, streaming, cookies through a network boundary, or browser-style `fetch`:
+
+```ts
+import { createTestServer } from 'remix/node-fetch-server/test'
+
+let server = await createTestServer((request) => router.fetch(request))
+try {
+  let response = await fetch(new URL(routes.home.href(), server.baseUrl))
+  assert.equal(response.status, 200)
+} finally {
+  await server.close()
+}
+```
+
+## Test Runner Config
+
+Configure discovery and coverage in `remix-test.config.ts` or with CLI flags:
+
+```ts
+export default {
+  glob: {
+    test: '**/*.test{,.e2e}.{ts,tsx}',
+    e2e: '**/*.test.e2e.{ts,tsx}',
+    exclude: 'node_modules/**',
+  },
+  coverage: {
+    dir: '.coverage',
+    include: ['app/**/*.{ts,tsx}'],
+    exclude: ['app/**/*.test.{ts,tsx}'],
+    statements: 80,
+    lines: 80,
+    branches: 70,
+    functions: 80,
+  },
+}
+```
+
+Use `remix test --coverage` to enable coverage with defaults. Use `glob.exclude` when discovery
+would otherwise enter generated output, symlinked workspaces, or other paths that should not
+produce tests.
+
+## Component Tests
+
+Use `render(...)` from `remix/ui/test` for most component tests. It creates a real DOM container,
+flushes the initial render, and returns `act(...)` so interactions can flush pending updates before
+assertions. Use `createRoot(container)` from `remix/ui` directly when a test needs explicit control
+over root rendering, flushing, or disposal.
+
+### Basic pattern
+
+```tsx
+import * as assert from 'remix/assert'
+import { render } from 'remix/ui/test'
+
+let result = render(<Counter />)
+
+let button = result.$('button')!
+await result.act(() => button.click())
+
+assert.match(result.container.textContent ?? '', /1/)
+result.cleanup()
+```
+
+### Why act / flush
+
+- **After initial render** — ensures event listeners are attached and the DOM is ready for
+  interaction.
+- **After interactions** — applies updates from `handle.update()` calls triggered by events.
+- **After async work resolves** — applies updates from resolved `queueTask(...)` callbacks.
+
+### Async operations
+
+For components with async operations in `queueTask`, use `act(...)` after each async step:
+
+```tsx
+let result = render(<AsyncLoader />)
+
+assert.equal(result.container.textContent, 'Loading...')
+
+await waitForFetch()
+await result.act(() => {})
+
+assert.equal(result.container.textContent, 'Expected data')
+```
+
+### Component removal
+
+Use `result.cleanup()` or `root.dispose()` to remove the component tree and verify cleanup
+behavior:
+
+```tsx
+let result = render(<MyComponent />)
+
+assert.ok(result.$('.content'))
+
+result.cleanup()
+assert.throws(() => result.$('.content'), /cleaned up/)
+```
+
+### Guidelines
+
+- Prefer real DOM interactions over mocking framework behavior.
+- Avoid testing implementation-only markers unless they are the only stable synchronization point.
+- One representative flow proving a behavior is better than repeating the same assertion across many
+  paths.

package/{bootstrap → template}/AGENTS.md

@@ -11,25 +11,30 @@ npm test
 npm run typecheck
 ```
 
+## Building Features
+
+Refer to ./.agents/skills/remix/SKILL.md
+
 ## Starter Layout
 
-- `app/controllers/home.tsx` owns the home page
-- `app/controllers/auth.tsx` owns the auth page
+- `app/actions/controller.tsx` owns the top-level route actions
 - `app/routes.ts` defines the route contract
 - `app/router.ts` wires routes to route handlers
-- `app/ui/` holds the shared document and layout wrappers
-- `app/utils/render.tsx` centralizes HTML response rendering
+- `app/middleware/render.tsx` installs the request-scoped renderer used by actions
+- `app/ui/` holds the shared document shell and home page UI
+- `app/assets.ts` owns the server-side asset pipeline used by the asset route and renderer
+- `public/` contains static files served from the app root
 
 ## Route Ownership
 
 - Start from `app/routes.ts` and map each route to the narrowest owner on disk.
-- Keep simple pages in flat files like `app/controllers/home.tsx` and `app/controllers/auth.tsx`.
-- Promote a route into a controller folder with `controller.tsx` only when it gains nested routes, multiple actions, or route-owned modules.
+- Put top-level route actions in `app/actions/controller.tsx`.
+- Add `app/actions/<route-key>/controller.tsx` for nested route maps that need their own actions or middleware.
 - Keep route-owned page modules next to the route that owns them.
-- Move shared UI to `app/ui/`, not `app/controllers/`.
+- Move shared UI to `app/ui/`, not `app/actions/`.
 
 ## Build-Out Notes
 
-- This starter intentionally begins small; add directories like `app/data/`, `app/middleware/`, `public/`, and `test/` only when you need them.
+- This starter intentionally begins small; add directories like `app/data/` and `test/` only when you need them.
 - Prefer putting code in the narrowest owner before introducing shared modules.
 - Avoid generic dumping-ground directories like `app/lib/` or `app/components/`.

package/template/README.md

@@ -0,0 +1,29 @@
+# %%RMX_APP_DISPLAY_NAME%%
+
+A minimal Remix application starter with a home page.
+
+## Starter Shape
+
+- `app/actions/controller.tsx` owns the top-level route actions.
+- `app/routes.ts` defines the route contract.
+- `app/router.ts` wires routes to handlers.
+- `app/middleware/render.tsx` installs the request-scoped renderer used by actions.
+- `app/ui/` holds the shared document shell and home page UI.
+- `app/assets.ts` owns the server-side asset pipeline used by the asset route and renderer.
+- `public/` contains static files served from the app root.
+
+## Growing The App
+
+- Put top-level route actions in `app/actions/controller.tsx`.
+- Add `app/actions/<route-key>/controller.tsx` when a nested route map needs its own actions or middleware.
+- Add directories like `app/data/` or `test/` when the app actually needs them.
+- Move shared UI into `app/ui/` once more than one route needs it.
+
+## Commands
+
+```sh
+npm i
+npm run start
+npm test
+npm run typecheck
+```

package/template/app/actions/controller.tsx

@@ -0,0 +1,18 @@
+import { createController } from 'remix/router'
+
+import { assetServer } from '../assets.ts'
+import { routes } from '../routes.ts'
+import { HomePage } from '../ui/scaffold-home-page.tsx'
+
+export default createController(routes, {
+  actions: {
+    async assets(context) {
+      return (
+        (await assetServer.fetch(context.request)) ?? new Response('Not Found', { status: 404 })
+      )
+    },
+    home(context) {
+      return context.render(<HomePage />)
+    },
+  },
+})

package/template/app/assets/entry.ts

@@ -0,0 +1,8 @@
+import { run } from 'remix/ui'
+
+run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+})