@remix-run/cli 0.5.0 → 0.7.0

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

@@ -66,31 +66,17 @@ 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}`)
-    }
-
-    let [href, preloads] = await Promise.all([
-      assetServer.getHref(entryId),
-      assetServer.getPreloads(entryId),
-    ])
+import { render } from 'remix/middleware/render'
 
-    return {
-      href,
-      exportName,
-      preloads,
-    }
-  },
+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.
 
@@ -102,39 +88,51 @@ The resolved `preloads` array contains browser module hrefs. During server rende
 
 Use `run` to start the client runtime. It scans the document for client entry markers, loads modules, and hydrates each one:
 
+Client entries introduced by later frame responses may depend on import map entries that were not in the initial document. Browsers without native support for multiple import maps cannot resolve those modules with `import()`. Apps that use asset server import maps and target these browsers can opt into `remix/multiple-import-maps-polyfill`:
+
 ```tsx
-import type { ResolveFrameOptions } from 'remix/ui'
+import {
+  detectMultipleImportMapSupport,
+  importModule,
+  preloadShim,
+} from 'remix/multiple-import-maps-polyfill'
 import { run } from 'remix/ui'
 
 const app = run({
   async loadModule(moduleUrl, exportName) {
-    let mod = await import(moduleUrl)
-    return mod[exportName]
+    let mod = await importModule(moduleUrl)
+    let Component = mod[exportName]
+    if (typeof Component !== 'function') {
+      throw new Error(`Unknown component: ${moduleUrl}#${exportName}`)
+    }
+    return Component
   },
-  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())
+  async processClientEntryPreloads(preloads) {
+    if (await detectMultipleImportMapSupport()) return preloads
+
+    preloadShim(preloads)
+    return []
   },
 })
 
-function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
-  let formData = options?.formData
-  if (!formData) return
-  if (options.encType !== 'application/x-www-form-urlencoded') return formData
+app.addEventListener('error', (event) => {
+  console.error('Component error:', event.error)
+})
 
-  let body = new URLSearchParams()
-  for (let [name, value] of formData) {
-    body.append(name, typeof value === 'string' ? value : value.name)
-  }
-  return body
-}
+await app.ready()
+```
+
+The support check keeps native imports and modulepreload links in browsers that support multiple import maps. Other browsers use the polyfill for late client entries and their preloads. Apps that do not need this compatibility can use `import()` directly in `loadModule` and omit `processClientEntryPreloads`.
+
+```tsx
+import { run } from 'remix/ui'
+
+const app = run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+})
 
 app.addEventListener('error', (event) => {
   console.error('Component error:', event.error)
@@ -143,10 +141,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
 
@@ -217,17 +227,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
 
@@ -235,9 +245,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'
@@ -292,7 +315,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,11 +64,12 @@ 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
 
 - Use `staticFiles()` for files that should be served directly from disk, such as images, fonts, or already-built assets in the root `public/` directory
-- Use `remix/assets` when browser modules should be compiled and served from source files with import rewriting, preloads, or fingerprinted URLs
+- Use `remix/assets` when browser modules should be compiled and served from source files with dependency resolution, preloads, or fingerprinted URLs
 - `public/` directories inside `app/` hold browser-reachable source for the asset server
 
 ### Ordering notes
@@ -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/actions/document.tsx

@@ -1,7 +1,8 @@
 import type { Handle, RemixNode } from 'remix/ui'
 import { css } from 'remix/ui'
+import { ImportMap } from 'remix/ui/server'
 
-import { entryHref, entryPreloads } from '../assets.ts'
+import { scriptEntry } from '../assets.ts'
 
 export interface DocumentProps {
   children?: RemixNode
@@ -14,6 +15,7 @@ const DEFAULT_TITLE = readAppDisplayName('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%
 export function Document(handle: Handle<DocumentProps>) {
   return () => {
     let { children, head, title = DEFAULT_TITLE } = handle.props
+    let { href, importMap, preloads } = scriptEntry
 
     return (
       <html lang="en">
@@ -24,10 +26,11 @@ export function Document(handle: Handle<DocumentProps>) {
           <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
           <title>{title}</title>
           {head}
-          {entryPreloads.map((href) => (
-            <link key={href} rel="modulepreload" href={href} />
+          <ImportMap value={importMap} />
+          {preloads.map((preloadHref) => (
+            <link key={preloadHref} rel="modulepreload" href={preloadHref} />
           ))}
-          <script type="module" src={entryHref}></script>
+          <script type="module" src={href}></script>
         </head>
         <body mix={css({ margin: 0 })}>{children}</body>
       </html>

package/template/app/actions/public/entry.ts

@@ -1,23 +1,24 @@
+import {
+  detectMultipleImportMapSupport,
+  importModule,
+  preloadShim,
+} from 'remix/multiple-import-maps-polyfill'
 import { run } from 'remix/ui'
 
 const app = run({
   async loadModule(moduleUrl, exportName) {
-    let mod = await import(moduleUrl)
-    return mod[exportName]
-  },
-  async resolveFrame(src, options) {
-    let response = await fetch(src, {
-      headers: { Accept: 'text/html' },
-      method: options?.method,
-      body: getRequestBody(options?.formData, options?.method, options?.encType),
-      signal: options?.signal,
-    })
-    if (!response.ok) {
-      return `<pre>Frame error: ${response.status} ${response.statusText}</pre>`
+    let mod = await importModule(moduleUrl)
+    let Component = mod[exportName]
+    if (typeof Component !== 'function') {
+      throw new Error(`Unknown component: ${moduleUrl}#${exportName}`)
     }
+    return Component
+  },
+  async processClientEntryPreloads(preloads) {
+    if (await detectMultipleImportMapSupport()) return preloads
 
-    if (response.body) return response.body
-    return await response.text()
+    preloadShim(preloads)
+    return []
   },
 })
 
@@ -31,18 +32,3 @@ if (import.meta.hot) {
     }
   })
 }
-
-function getRequestBody(
-  formData?: FormData,
-  method?: string,
-  encType?: string,
-): BodyInit | undefined {
-  if (!formData || method?.toLowerCase() === 'get') return
-  if (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
-}

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.*'],
@@ -20,12 +17,14 @@ export const assetServer = createAssetServer({
   minify: !isDevelopment,
   watch: isDevelopment,
   hmr: isHmr
-    ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+    ? {
+        channel: async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel(),
+        moduleImporter: 'remix/multiple-import-maps-polyfill',
+      }
     : undefined,
   scripts: { loaders: isHmr ? [uiHmr()] : undefined },
 })
 
 const entry = 'app/actions/public/entry.ts'
 
-export const entryHref = await assetServer.getHref(entry)
-export const entryPreloads = await assetServer.getPreloads(entry)
+export const scriptEntry = await assets.getScriptEntry(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,78 +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 and preloads.
-          async resolveClientEntry(entryId, component) {
-            if (!entryId.startsWith('file://')) {
-              throw new Error(
-                `Expected \`import.meta.url\` for clientEntry ID, received '${entryId}'`,
-              )
-            }
-
-            let [href, preloads] = await Promise.all([
-              assetServer.getHref(entryId),
-              assetServer.getPreloads(entryId),
-            ])
-
-            return {
-              href,
-              exportName: entryId.split('#')[1] || component.name || titleCaseFileName(entryId),
-              preloads,
-            }
-          },
-        })
-
-        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('')
-}