@remix-run/cli 0.2.0 → 0.3.0

package/{bootstrap → template}/.agents/skills/remix/references/data-and-validation.md

@@ -84,9 +84,16 @@ runtime only needs the column shape and validation hooks. Two valid patterns:
 
 Pick one and apply it consistently across the app.
 
-### Table validation hooks
+### Table lifecycle hooks
 
-Tables can define `validate`, `beforeWrite`, and `afterRead` 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({
@@ -94,6 +101,12 @@ export const books = table({
   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) {
@@ -101,6 +114,9 @@ export const books = table({
     }
     return issues.length > 0 ? { issues } : { value }
   },
+  afterRead({ value }) {
+    return { value }
+  },
 })
 ```
 
@@ -111,7 +127,7 @@ 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'
+import { createSqliteDatabaseAdapter } from 'remix/data-table/sqlite'
 
 let sqlite = new BetterSqlite3('./db/app.db')
 sqlite.pragma('foreign_keys = ON')
@@ -126,7 +142,7 @@ client fits the runtime instead of assuming `better-sqlite3` is required.
 ### Database middleware
 
 ```typescript
-import type { Middleware } from 'remix/fetch-router'
+import type { Middleware } from 'remix/router'
 import { Database } from 'remix/data-table'
 
 export function loadDatabase(): Middleware {
@@ -284,7 +300,7 @@ The recommended way: register `formData()` middleware in the root stack and read
 the context system. This also lets `methodOverride()` and CSRF middleware work uniformly.
 
 ```typescript
-import { formData } from 'remix/form-data-middleware'
+import { formData } from 'remix/middleware/form-data'
 
 let router = createRouter({
   middleware: [, /* ... */ formData() /* ... */],

package/{bootstrap → template}/.agents/skills/remix/references/middleware-and-server.md

@@ -9,7 +9,7 @@ involves:
 - Writing custom middleware that sets typed context values
 - Adding fast-exit handling (static files, CORS preflights) versus request-enriching layers
   (sessions, auth, data loading)
-- Booting a Node `http` server with `createRequestListener`
+- Choosing when to keep the generated Node server versus switching server adapters
 
 For data and persistence specifics, see `data-and-validation.md`. For session and auth specifics,
 see `auth-and-sessions.md`.
@@ -22,14 +22,14 @@ request-enriching middleware (session, auth) later.
 Recommended ordering:
 
 ```typescript
-import { createRouter } from 'remix/fetch-router'
-import { compression } from 'remix/compression-middleware'
-import { formData } from 'remix/form-data-middleware'
-import { logger } from 'remix/logger-middleware'
-import { methodOverride } from 'remix/method-override-middleware'
-import { session } from 'remix/session-middleware'
-import { staticFiles } from 'remix/static-middleware'
-import { asyncContext } from 'remix/async-context-middleware'
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+import { formData } from 'remix/middleware/form-data'
+import { logger } from 'remix/middleware/logger'
+import { methodOverride } from 'remix/middleware/method-override'
+import { session } from 'remix/middleware/session'
+import { staticFiles } from 'remix/middleware/static'
+import { asyncContext } from 'remix/middleware/async-context'
 
 let middleware = []
 
@@ -53,18 +53,18 @@ let router = createRouter({ middleware })
 
 | Middleware                 | Import                             | Use when                                                                      | Notes                                                          |
 | -------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `staticFiles(dir, opts?)`  | `remix/static-middleware`          | Serve files from `public/` or another directory exactly as they exist on disk | Fast exit; usually near the top                                |
-| `compression()`            | `remix/compression-middleware`     | Compress text-like responses                                                  | Usually global                                                 |
-| `logger()`                 | `remix/logger-middleware`          | Log requests and responses                                                    | Often development-only; `colors` can force color output on/off |
-| `cors(opts?)`              | `remix/cors-middleware`            | Endpoints must serve cross-origin browsers or preflight `OPTIONS` requests    | Usually early so preflights can short-circuit                  |
-| `cop(opts?)`               | `remix/cop-middleware`             | Reject unsafe cross-origin browser requests without synchronizer tokens       | Put before session or CSRF when used                           |
-| `formData(opts?)`          | `remix/form-data-middleware`       | Parse `FormData` bodies, especially forms and uploads                         | Needed for `_csrf` form field extraction                       |
-| `methodOverride()`         | `remix/method-override-middleware` | HTML forms need `PUT`, `PATCH`, or `DELETE` semantics                         | Run after form parsing                                         |
-| `session(cookie, storage)` | `remix/session-middleware`         | Cookie-backed sessions                                                        | Must run before session-backed auth or CSRF                    |
-| `csrf(opts?)`              | `remix/csrf-middleware`            | Session-backed form workflows need synchronizer-token CSRF protection         | Requires `session()` before it                                 |
-| `asyncContext()`           | `remix/async-context-middleware`   | Helpers outside handlers need request context via `getContext()`              | Add before helpers rely on it                                  |
-| `auth({ schemes })`        | `remix/auth-middleware`            | Resolve auth state into `context.get(Auth)`                                   | Run after `session()` for session-backed auth                  |
-| `requireAuth()`            | `remix/auth-middleware`            | A controller or action must reject anonymous access                           | Usually controller-level or action-level, not global           |
+| `staticFiles(dir, opts?)`  | `remix/middleware/static`          | Serve files from `public/` or another directory exactly as they exist on disk | Fast exit; usually near the top                                |
+| `compression()`            | `remix/middleware/compression`     | Compress text-like responses                                                  | Usually global                                                 |
+| `logger()`                 | `remix/middleware/logger`          | Log requests and responses                                                    | Often development-only; `colors` can force color output on/off |
+| `cors(opts?)`              | `remix/middleware/cors`            | Endpoints must serve cross-origin browsers or preflight `OPTIONS` requests    | Usually early so preflights can short-circuit                  |
+| `cop(opts?)`               | `remix/middleware/cop`             | Reject unsafe cross-origin browser requests without synchronizer tokens       | Put before session or CSRF when used                           |
+| `formData(opts?)`          | `remix/middleware/form-data`       | Parse `FormData` bodies, especially forms and uploads                         | Needed for `_csrf` form field extraction                       |
+| `methodOverride()`         | `remix/middleware/method-override` | HTML forms need `PUT`, `PATCH`, or `DELETE` semantics                         | Run after form parsing                                         |
+| `session(cookie, storage)` | `remix/middleware/session`         | Cookie-backed sessions                                                        | Must run before session-backed auth or CSRF                    |
+| `csrf(opts?)`              | `remix/middleware/csrf`            | Session-backed form workflows need synchronizer-token CSRF protection         | Requires `session()` before it                                 |
+| `asyncContext()`           | `remix/middleware/async-context`   | Helpers outside handlers need request context via `getContext()`              | Add before helpers rely on it                                  |
+| `auth({ schemes })`        | `remix/middleware/auth`            | Resolve auth state into `context.get(Auth)`                                   | Run after `session()` for session-backed auth                  |
+| `requireAuth()`            | `remix/middleware/auth`            | A controller or action must reject anonymous access                           | Usually controller-level or action-level, not global           |
 
 ### Static files vs browser modules
 
@@ -103,7 +103,7 @@ staticFiles('./public', {
 })
 
 // Form data with upload handler
-import { FileUpload } from 'remix/form-data-parser'
+import type { FileUpload } from 'remix/form-data-parser'
 import { createFsFileStorage } from 'remix/file-storage/fs'
 
 let fileStorage = createFsFileStorage('./tmp/uploads')
@@ -120,15 +120,16 @@ errors at the route boundary when they should become user-facing `Response` obje
 
 ## Writing Custom Middleware
 
-Middleware is a function that receives `(context, next)` and returns a `Response`. Call `next()` to
-continue the chain.
+Middleware is a function that receives `(context, next)`. Return a `Response` to short-circuit, call
+and return `next()` when you need the downstream response, or return nothing when you only set
+context and want the router to continue automatically.
 
 ### Setting context values
 
 Use `context.set(key, value)` to add typed values accessible downstream via `context.get(key)`.
 
 ```typescript
-import type { Middleware } from 'remix/fetch-router'
+import type { Middleware } from 'remix/router'
 import { Database } from 'remix/data-table'
 
 export function loadDatabase(): Middleware {
@@ -142,7 +143,7 @@ export function loadDatabase(): Middleware {
 ### Guarding routes
 
 ```typescript
-import { Auth } from 'remix/auth-middleware'
+import { Auth } from 'remix/middleware/auth'
 
 export function requireAdmin(): Middleware {
   return (context, next) => {
@@ -163,8 +164,8 @@ helpers:
 
 ```typescript
 // app/utils/context.ts
-import { getContext } from 'remix/async-context-middleware'
-import { Auth } from 'remix/auth-middleware'
+import { getContext } from 'remix/middleware/async-context'
+import { Auth } from 'remix/middleware/auth'
 import { Database } from 'remix/data-table'
 import { Session } from 'remix/session'
 
@@ -200,18 +201,21 @@ Middleware can be applied at three levels:
    let router = createRouter({ middleware: [...] })
    ```
 
-2. **Controller-level** — runs for all actions in a controller subtree:
+2. **Controller-level** — runs for the direct actions in one controller:
 
    ```typescript
-   export default {
+   export default createController(routes.account, {
      middleware: [requireAuth()],
      actions: { ... },
-   } satisfies Controller<typeof routes.account>
+   })
    ```
 
+   Controller middleware does not flow into other controllers. Add the middleware to each
+   controller that needs it.
+
 3. **Action-level** — runs for a single route:
    ```typescript
-   router.get(routes.account, {
+   router.get(routes.account.index, {
      middleware: [requireAuth()],
      handler: accountAction.handler,
    })
@@ -219,25 +223,11 @@ Middleware can be applied at three levels:
 
 ## Node Server Setup
 
-Use `createRequestListener` to bridge Node's `http` module to the Fetch API router:
+New apps already include a `server.ts` that adapts the app router with
+`remix/node-fetch-server`. Keep that generated server unless the task specifically needs to change
+runtime behavior such as host/protocol handling, TLS, HTTP/2, WebSockets, deployment lifecycle, or
+test-only server setup.
 
-```typescript
-import * as http from 'node:http'
-import { createRequestListener } from 'remix/node-fetch-server'
-
-let server = http.createServer(
-  createRequestListener(async (request) => {
-    try {
-      return await router.fetch(request)
-    } catch (error) {
-      console.error(error)
-      return new Response('Internal Server Error', { status: 500 })
-    }
-  }),
-)
-
-let port = Number(process.env.PORT) || 3000
-server.listen(port, () => {
-  console.log(`http://localhost:${port}`)
-})
-```
+Use `remix/node-fetch-server` when you want to keep owning a standard Node `http`, `https`, or
+`http2` server directly. Use `remix/node-serve` and `serve()` when you want a managed
+high-performance server with `server.ready`, TLS options, or uWebSockets.js setup.

package/{bootstrap → template}/.agents/skills/remix/references/routing-and-controllers.md

@@ -17,7 +17,7 @@ data is `data-and-validation.md`. For request lifecycle and middleware ordering,
 
 ## Route Builders
 
-Import all route builders from `remix/fetch-router/routes`.
+Import all route builders from `remix/routes`.
 
 ### `route(prefix, map)` — nested route group
 
@@ -27,7 +27,7 @@ call (when you want a shared URL prefix) or a plain object literal (when each le
 its absolute path).
 
 ```typescript
-import { route, get, post } from 'remix/fetch-router/routes'
+import { route, get, post } from 'remix/routes'
 
 export const routes = route({
   home: '/',
@@ -92,18 +92,22 @@ redirect(routes.account.orders.show.href({ orderId: '42' }))
 
 ## Actions
 
-An action is a handler for a single leaf route. Type it with `BuildAction`:
+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 type { BuildAction } from 'remix/fetch-router'
+import { createAction } from 'remix/router'
 
-export const search: BuildAction<'GET', typeof routes.search> = {
+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:
@@ -116,9 +120,9 @@ The handler receives a context object with:
 Actions with inline middleware:
 
 ```typescript
-import { requireAuth } from 'remix/auth-middleware'
+import { requireAuth } from 'remix/middleware/auth'
 
-router.get(routes.account, {
+router.get(routes.account.index, {
   middleware: [requireAuth()],
   handler: accountAction.handler,
 })
@@ -195,17 +199,18 @@ if (!parsed.success) {
 ### 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 `remix/headers` for cache headers
-instead of hand-formatting strings:
+APIs, inter-service calls), return a JSON `Response`. Use `SuperHeaders` from `remix/headers` when
+typed header accessors make the response clearer:
 
 ```typescript
-import { CacheControl } from 'remix/headers'
+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: {
-    'Content-Type': 'application/json; charset=utf-8',
-    'Cache-Control': new CacheControl({ noStore: true }).toString(),
-  },
+  headers,
 })
 ```
 
@@ -216,15 +221,20 @@ with the server.
 
 ## Controllers
 
-A controller mirrors a route map. Each key in `actions` matches a key in the route definition.
-Pass `AppContext` as the second generic to `Controller` so `get(Database)`, `get(Session)`,
-`get(Auth)`, etc. are typed against your middleware stack.
+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 type { Controller } from 'remix/fetch-router'
-import type { AppContext } from '../router.ts'
+import { createController } from 'remix/router'
+
+import { routes } from '../routes.ts'
 
-export default {
+export default createController(routes.books, {
   actions: {
     async index({ get }) {
       let db = get(Database)
@@ -239,74 +249,125 @@ export default {
       return render(<ShowPage book={book} />)
     },
   },
-} satisfies Controller<typeof routes.books, AppContext>
+})
 ```
 
-### Nested controllers
+### Root controller
 
-When a route map contains nested maps, the controller nests too:
+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' } }),
-    orders: resources('orders', { only: ['index', 'show'], param: 'orderId' }),
   }),
 })
 
-// controllers/account/controller.tsx
-import settingsController from './settings/controller.tsx'
-import ordersController from './orders/controller.tsx'
+// 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.
 
-export default {
+```typescript
+// app/actions/account/controller.tsx
+export default createController(routes.account, {
   middleware: [requireAuth()],
   actions: {
-    index() { return render(<AccountPage />) },
-    settings: settingsController,
-    orders: ordersController,
+    index() {
+      return render(<AccountPage />)
+    },
   },
-} satisfies Controller<typeof routes.account, AppContext>
+})
+
+// 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 for every action in that subtree, before action-level
-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 {
+export default createController(routes.admin, {
   middleware: [requireAuth(), requireAdmin()],
   actions: {
     /* all actions require auth + admin */
   },
-} satisfies Controller<typeof routes.admin, AppContext>
+})
 ```
 
 ## Registering Routes
 
-Use `router.map` for route maps (controllers) and verb methods for leaf 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 map → controller
+// 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 → action
-router.map(routes.home, home)
+// 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 for use in actions and controllers:
+Define an `AppContext` type from your middleware stack, then make it the default context used by
+`createAction()` and `createController()`:
 
 ```typescript
-import type { MiddlewareContext, WithParams, AnyParams } from 'remix/fetch-router'
+import type { MiddlewareContext, ContextWithParams, AnyParams } from 'remix/router'
 
 type RootMiddleware = [
   ReturnType<typeof formData>,
@@ -315,10 +376,16 @@ type RootMiddleware = [
   ReturnType<typeof loadAuth>,
 ]
 
-export type AppContext<params extends AnyParams = AnyParams> = WithParams<
+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/{bootstrap → template}/.agents/skills/remix/references/testing-patterns.md

@@ -9,6 +9,7 @@ the task involves:
 - 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
@@ -54,7 +55,7 @@ a known session, swap in `createMemorySessionStorage()` and a test cookie when c
 router.
 
 ```ts
-import { createMemorySessionStorage } from 'remix/session/memory-storage'
+import { createMemorySessionStorage } from 'remix/session-storage/memory'
 import { createCookie } from 'remix/cookie'
 
 let router = createBookstoreRouter({
@@ -63,6 +64,21 @@ let router = createBookstoreRouter({
 })
 ```
 
+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:

package/{bootstrap → template}/AGENTS.md

@@ -13,27 +13,28 @@ npm run typecheck
 
 ## Building Features
 
-Refer to ./agents/skills/remix/SKILL.md
+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]
+  },
+})

package/{bootstrap/app/ui → template/app/assets}/prompt-button.tsx

@@ -9,8 +9,9 @@ interface PromptButtonProps extends SerializableProps {
   text: string
 }
 
+// This component hydrates independently; the rest of the page stays static HTML.
 export const PromptButton = clientEntry(
-  '/assets/app/ui/prompt-button.tsx#PromptButton',
+  import.meta.url,
   function PromptButton(handle: Handle<PromptButtonProps>) {
     let state: CopyState = 'idle'