@remix-run/cli 0.4.0 → 0.6.0

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

@@ -66,36 +66,29 @@ export const Counter = clientEntry(
 )
 ```
 
-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:
+On the server, pass the asset server to the standard render middleware so source file URLs become browser-loadable asset URLs without hard-coding deployment paths in component modules:
 
 ```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,
-    }
-  },
+import { render } from 'remix/middleware/render'
+
+let router = createRouter({
+  middleware: [render({ assets: assetServer })],
 })
 ```
 
-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.
+If the module export name differs from the component function name, include `#ExportName` in the entry ID. Custom rendering pipelines may instead provide the exact export name through `renderToStream({ resolveClientEntry })`.
 
 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.
 
+The resolved `preloads` array contains browser module hrefs. During server rendering these are emitted as `<link rel="modulepreload">` tags, including preloads discovered in blocking frames. When a later frame response introduces a client entry, its preloads start before the entry module is loaded.
+
 ## 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 type { ResolveFrameOptions } from 'remix/ui'
 import { run } from 'remix/ui'
 
 const app = run({
@@ -103,31 +96,8 @@ const app = run({
     let mod = await import(moduleUrl)
     return mod[exportName]
   },
-  async resolveFrame(src, options) {
-    let headers = new Headers({ accept: 'text/html', 'x-remix-frame': 'true' })
-    if (options?.target) headers.set('x-remix-target', options.target)
-    let response = await fetch(src, {
-      body: getRequestBody(options),
-      headers,
-      method: options?.method,
-      signal: options?.signal,
-    })
-    return response.body ?? (await response.text())
-  },
 })
 
-function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
-  let formData = options?.formData
-  if (!formData) return
-  if (options.encType !== 'application/x-www-form-urlencoded') return formData
-
-  let body = new URLSearchParams()
-  for (let [name, value] of formData) {
-    body.append(name, typeof value === 'string' ? value : value.name)
-  }
-  return body
-}
-
 app.addEventListener('error', (event) => {
   console.error('Component error:', event.error)
 })
@@ -135,10 +105,22 @@ app.addEventListener('error', (event) => {
 await app.ready()
 ```
 
+By default, `run()` resolves frames with `fetch()`, requests `text/html`, and forwards the submitted
+method and abort signal. GET form values are already encoded in `src`; non-GET submissions use
+`URLSearchParams` for `application/x-www-form-urlencoded`, CRLF-delimited text for `text/plain`, and
+`FormData` for `multipart/form-data`. Provide `resolveFrame` when an app needs additional headers,
+another body encoding, or a different response policy.
+
+Add `data-rmx-document` to a link or form to leave its navigation to the browser.
+
+The default resolver rejects non-OK responses with an error containing their status and status text.
+A custom `resolveFrame` may return a `Response` with any status when it wants the runtime to render
+the response body.
+
 ### `run` options
 
 - **`loadModule(moduleUrl, exportName)`** (required) — return the component function for each client entry. Typically uses dynamic `import()`.
-- **`resolveFrame(src, options)`** (optional) — called when a `<Frame>` loads or reloads content and for intercepted link and form navigations. `options` may contain `signal` and `target`; non-GET forms also provide `formData`, `method`, and `encType`.
+- **`resolveFrame(src, options)`** (optional) — overrides the default `fetch()` resolver when a `<Frame>` loads or reloads content and for intercepted link and form navigations. `options` may contain `signal` and `target`; non-GET forms also provide `formData`, `method`, and `encType`.
 
 ### `app` methods
 
@@ -209,17 +191,17 @@ When a frame reloads, matching DOM nodes are updated in place. Client entries re
 
 ### Form navigation
 
-When `run({ resolveFrame })` is active, eligible same-origin forms progressively enhance into frame navigations. Native validation and the form's `submit` event still run first.
+When `run()` is active, eligible same-origin forms progressively enhance into frame navigations. Native validation and the form's `submit` event still run first.
 
 - Forms target `handle.frames.top` by default.
-- `rmx-target` selects a named frame.
-- `rmx-src` selects a different frame request URL while preserving the form action as the navigation destination.
-- `rmx-history="push|replace"` overrides how the navigation updates history.
-- `rmx-reset-scroll="false"` preserves scroll position.
-- `rmx-document` opts back into a document submission.
+- `data-rmx-target` selects a named frame.
+- `data-rmx-src` selects a different frame request URL while preserving the form action as the navigation destination.
+- `data-rmx-history="push|replace"` overrides how the navigation updates history.
+- `data-rmx-reset-scroll="false"` preserves scroll position.
+- `data-rmx-document` opts back into a document submission.
 - Cross-origin forms, `method="dialog"`, and `target="_blank"` remain browser-owned.
 
-GET controls are already encoded in `src`, so GET forms reach the resolver like links. Non-GET forms provide their native `FormData`, effective method, and encoding. The resolver owns body encoding and method-override conventions. Non-GET submissions to the current URL replace its history entry; GET submissions and submissions to a different URL push one. The `rmx-history` attribute overrides those defaults.
+GET controls are already encoded in `src`, so GET forms reach the resolver like links. Non-GET forms provide their native `FormData`, effective method, and encoding. The resolver owns body encoding and method-override conventions. Non-GET submissions to the current URL replace its history entry; GET submissions and submissions to a different URL push one. The `data-rmx-history` attribute overrides those defaults.
 
 ### Nested frames
 
@@ -227,9 +209,22 @@ Frames can nest. Each frame owns its own DOM region and hydrates client entries
 
 ## Server Rendering
 
+Normal applications install the conventional middleware and render at the action boundary:
+
+```tsx
+import { render } from 'remix/middleware/render'
+import { createRouter } from 'remix/router'
+
+let router = createRouter({ middleware: [render()] })
+
+router.get('/', (context) => context.render(<App />, { status: 200 }))
+```
+
+The middleware seeds frame URLs from the request, resolves nested and targeted frames through the current router, forwards session and authentication headers safely, follows frame redirects, preserves application error bodies, and cancels rendering with the request.
+
 ### `renderToStream`
 
-Renders a component tree to a `ReadableStream<Uint8Array>`. Sends initial HTML immediately and streams frame content as it resolves:
+Use this low-level API when replacing the standard response pipeline. It 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'
@@ -284,7 +279,7 @@ navigate('/dashboard', { history: 'replace' })
 
 Options: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
 
-Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-history`, `rmx-reset-scroll`, `rmx-document`.
+Attributes understood by the runtime: `data-rmx-target`, `data-rmx-src`, `data-rmx-history`, `data-rmx-reset-scroll`, `data-rmx-document`.
 
 ## Head Management
 

package/template/.agents/skills/remix/references/middleware-and-server.md

@@ -24,6 +24,7 @@ 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 { render } from 'remix/middleware/render'
 import { session } from 'remix/middleware/session'
 import { staticFiles } from 'remix/middleware/static'
 import { asyncContext } from 'remix/middleware/async-context'
@@ -42,6 +43,7 @@ middleware.push(session(cookie, storage))
 middleware.push(asyncContext())
 middleware.push(loadDatabase())
 middleware.push(loadAuth())
+middleware.push(render({ assets }))
 
 let router = createRouter({ middleware })
 ```
@@ -62,6 +64,7 @@ let router = createRouter({ middleware })
 | `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 middleware or action middleware             |
+| `render({ assets? })`      | `remix/middleware/render`          | Actions render Remix UI through `context.render(node, init)`                  | Pass the asset server for source-based client entries          |
 
 ### Static files vs browser modules
 
@@ -79,7 +82,7 @@ let router = createRouter({ middleware })
 
 ### Common stacks
 
-- **Session-backed HTML app** -> `compression()`, `staticFiles()`, optional `cop()`, `formData()`, `methodOverride()`, `session()`, optional `csrf()`, `asyncContext()`, `auth({ schemes })`
+- **Session-backed HTML app** -> `compression()`, `staticFiles()`, optional `cop()`, `formData()`, `methodOverride()`, `session()`, optional `csrf()`, `asyncContext()`, `auth({ schemes })`, `render({ assets })`
 - **Cross-origin API** -> `compression()`, `cors()`, optional `asyncContext()`, optional `auth({ schemes })`
 - **Upload flow** -> `compression()`, `staticFiles()`, `formData({ uploadHandler })`, then sessions, auth, and data-loading middleware as needed
 - **Optional development HMR** -> keep `server.ts` as the child app server, add `hmr.ts` for `remix/node-hmr`, and proxy public requests through `createHmrReadyFetch()`

package/template/.agents/skills/remix/references/mixins-styling-events.md

@@ -115,7 +115,7 @@ Adds client-side navigation behavior to any element. Makes non-anchor elements b
 
 Options match `NavigationOptions`: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
 
-On a native anchor, the `history` option renders the corresponding `rmx-history="push|replace"` attribute so the enhanced navigation uses the same history behavior.
+On a native anchor, the `history` option renders the corresponding `data-rmx-history="push|replace"` attribute so the enhanced navigation uses the same history behavior.
 
 ## Native press and keyboard interactions
 

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

@@ -252,7 +252,7 @@ export const routes = route({
 export default createController(routes, {
   actions: {
     async assets({ request }) {
-      return (await assetServer.fetch(request)) ?? new Response('Not Found', { status: 404 })
+      return (await assets.fetch(request)) ?? new Response('Not Found', { status: 404 })
     },
     home() {
       return render(<HomePage />)

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

@@ -74,7 +74,7 @@ Configure discovery and coverage in the `test` section of `remix.json` or with C
 
 ```jsonc
 {
-  "$schema": "https://remix.run/schemas/remix.json",
+  "$schema": "./node_modules/remix/schema/remix.json",
   "test": {
     "files": ["**/*.test{,.e2e}.{ts,tsx}"],
     "e2eFiles": ["**/*.test.e2e.{ts,tsx}"],

package/template/AGENTS.md

@@ -23,9 +23,8 @@ Refer to ./.agents/skills/remix/SKILL.md
 - `app/actions/home-page.tsx` and `app/actions/document.tsx` render the route-owned starter UI
 - `app/actions/public/` contains the browser runtime entry and interactive prompt button
 - `app/routes.ts` defines the shared route contract used by server and browser modules for type-safe hrefs
-- `app/router.ts` wires routes to route handlers
-- `app/middleware/render.tsx` installs the request-scoped renderer used by actions
-- `app/assets.ts` owns the server-side asset pipeline used by the asset route and renderer
+- `app/router.ts` wires routes to route handlers and installs the standard Remix UI renderer used by actions
+- `app/assets.ts` owns the server-side asset pipeline used by the asset route and render middleware
 - Root `public/` contains static files served unchanged from the app root
 
 ## Route Ownership

package/template/README.md

@@ -8,9 +8,8 @@ A minimal Remix application starter with a home page.
 - `app/actions/home-page.tsx` and `app/actions/document.tsx` render the route-owned starter UI.
 - `app/actions/public/` contains the browser runtime entry and interactive prompt button.
 - `app/routes.ts` defines the shared route contract used by server and browser modules for type-safe hrefs.
-- `app/router.ts` wires routes to handlers.
-- `app/middleware/render.tsx` installs the request-scoped renderer used by actions.
-- `app/assets.ts` owns the server-side asset pipeline used by the asset route and renderer.
+- `app/router.ts` wires routes to handlers and installs the standard Remix UI renderer used by actions.
+- `app/assets.ts` owns the server-side asset pipeline used by the asset route and render middleware.
 - Root `public/` contains static files served unchanged from the app root.
 
 ## Growing The App

package/template/app/actions/controller.tsx

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

package/template/app/assets.ts

@@ -6,13 +6,10 @@ const nodeEnv = process.env.NODE_ENV ?? 'development'
 const isDevelopment = nodeEnv === 'development'
 const isHmr = Boolean(isDevelopment && process.env.REMIX_NODE_HMR)
 
-export const assetServer = createAssetServer({
+export const assets = createAssetServer({
   basePath: '/assets',
   rootDir,
-  fileMap: {
-    'app/*path': 'app/*path',
-    'node_modules/*path': 'node_modules/*path',
-  },
+
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   denyFiles: ['app/**/*.test.*'],
@@ -27,5 +24,5 @@ export const assetServer = createAssetServer({
 
 const entry = 'app/actions/public/entry.ts'
 
-export const entryHref = await assetServer.getHref(entry)
-export const entryPreloads = await assetServer.getPreloads(entry)
+export const entryHref = await assets.getHref(entry)
+export const entryPreloads = await assets.getPreloads(entry)

package/template/app/router.ts

@@ -1,11 +1,13 @@
 import { createRouter, type MiddlewareContext } from 'remix/router'
+import { render } from 'remix/middleware/render'
 import { staticFiles } from 'remix/middleware/static'
 
 import controller from './actions/controller.tsx'
-import { render } from './middleware/render.tsx'
+import { assets } from './assets.ts'
 import { routes } from './routes.ts'
 
-type AppContext = MiddlewareContext<[ReturnType<typeof render>]>
+const renderMiddleware = render({ assets })
+type AppContext = MiddlewareContext<[typeof renderMiddleware]>
 
 declare module 'remix/router' {
   interface RouterTypes {
@@ -14,7 +16,7 @@ declare module 'remix/router' {
 }
 
 export const router = createRouter<AppContext>({
-  middleware: [staticFiles('./public', { index: false }), render()],
+  middleware: [staticFiles('./public', { index: false }), renderMiddleware],
 })
 
 router.map(routes, controller)

package/template/app/middleware/render.tsx

@@ -1,72 +0,0 @@
-import * as path from 'node:path'
-
-import type { Router } from 'remix/router'
-import { renderWith } from 'remix/middleware/render'
-import { createHtmlResponse } from 'remix/response/html'
-import type { RemixNode } from 'remix/ui'
-import { renderToStream } from 'remix/ui/server'
-
-import { assetServer } from '../assets.ts'
-
-export function render() {
-  return renderWith(
-    ({ request, router }) =>
-      function render(node: RemixNode, init?: ResponseInit) {
-        let stream = renderToStream(node, {
-          frameSrc: request.url,
-          signal: request.signal,
-          resolveFrame: (src) => resolveFrame(router, request, src),
-          // Server rendering turns client entries into browser module URLs.
-          async resolveClientEntry(entryId, component) {
-            if (!entryId.startsWith('file://')) {
-              throw new Error(
-                `Expected \`import.meta.url\` for clientEntry ID, received '${entryId}'`,
-              )
-            }
-
-            return {
-              href: await assetServer.getHref(entryId),
-              exportName: entryId.split('#')[1] || component.name || titleCaseFileName(entryId),
-            }
-          },
-        })
-
-        return createHtmlResponse(stream, init)
-      },
-  )
-}
-
-async function resolveFrame(router: Router, request: Request, src: string) {
-  let url = new URL(src, request.url)
-
-  let headers = new Headers()
-  headers.set('Accept', 'text/html')
-
-  let cookie = request.headers.get('Cookie')
-  if (cookie) headers.set('Cookie', cookie)
-
-  let response = await router.fetch(
-    new Request(url, {
-      method: 'GET',
-      headers,
-      signal: request.signal,
-    }),
-  )
-
-  if (!response.ok) {
-    return `<pre>Frame error: ${response.status} ${response.statusText}</pre>`
-  }
-
-  if (response.body) return response.body
-  return await response.text()
-}
-
-function titleCaseFileName(fileUrl: string): string {
-  let url = new URL(fileUrl)
-  let fileName = path.basename(url.pathname, path.extname(url.pathname))
-  return fileName
-    .split(/[^A-Za-z0-9]+/)
-    .filter(Boolean)
-    .map((segment) => segment[0]!.toUpperCase() + segment.slice(1))
-    .join('')
-}