npm - @remix-run/cli - Versions diffs - 0.3.4 → 0.5.0 - Mend

@remix-run/cli 0.3.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/README.md +105 -1
package/dist/index.js +1 -1
package/dist/lib/app-root.d.ts +11 -0
package/dist/lib/app-root.d.ts.map +1 -0
package/dist/lib/app-root.js +38 -0
package/dist/lib/bootstrap-project.js +2 -2
package/dist/lib/cli-context.d.ts +6 -0
package/dist/lib/cli-context.d.ts.map +1 -1
package/dist/lib/cli-context.js +12 -1
package/dist/lib/cli.d.ts +3 -2
package/dist/lib/cli.d.ts.map +1 -1
package/dist/lib/cli.js +42 -14
package/dist/lib/commands/completion.js +4 -4
package/dist/lib/commands/db.d.ts +4 -0
package/dist/lib/commands/db.d.ts.map +1 -0
package/dist/lib/commands/db.js +283 -0
package/dist/lib/commands/doctor.d.ts +5 -0
package/dist/lib/commands/doctor.d.ts.map +1 -1
package/dist/lib/commands/doctor.js +26 -251
package/dist/lib/commands/help.d.ts.map +1 -1
package/dist/lib/commands/help.js +17 -9
package/dist/lib/commands/new.js +6 -6
package/dist/lib/commands/routes.js +6 -6
package/dist/lib/commands/test.d.ts +20 -1
package/dist/lib/commands/test.d.ts.map +1 -1
package/dist/lib/commands/test.js +353 -10
package/dist/lib/commands/version.js +3 -3
package/dist/lib/completion.d.ts +1 -1
package/dist/lib/completion.d.ts.map +1 -1
package/dist/lib/completion.js +229 -6
package/dist/lib/controller-files.d.ts +0 -8
package/dist/lib/controller-files.d.ts.map +1 -1
package/dist/lib/controller-files.js +0 -23
package/dist/lib/controller-ownership.d.ts +4 -12
package/dist/lib/controller-ownership.d.ts.map +1 -1
package/dist/lib/controller-ownership.js +31 -127
package/dist/lib/database-command.d.ts +20 -0
package/dist/lib/database-command.d.ts.map +1 -0
package/dist/lib/database-command.js +7 -0
package/dist/lib/doctor/controller-findings.d.ts +2 -2
package/dist/lib/doctor/controller-findings.d.ts.map +1 -1
package/dist/lib/doctor/controller-findings.js +23 -39
package/dist/lib/doctor/controllers.d.ts +1 -2
package/dist/lib/doctor/controllers.d.ts.map +1 -1
package/dist/lib/doctor/controllers.js +4 -7
package/dist/lib/doctor/environment.js +2 -2
package/dist/lib/doctor/fixes.js +1 -1
package/dist/lib/doctor/project.d.ts.map +1 -1
package/dist/lib/doctor/project.js +3 -212
package/dist/lib/doctor/run.d.ts +9 -0
package/dist/lib/doctor/run.d.ts.map +1 -0
package/dist/lib/doctor/run.js +237 -0
package/dist/lib/doctor/types.d.ts +2 -1
package/dist/lib/doctor/types.d.ts.map +1 -1
package/dist/lib/doctor/types.js +4 -1
package/dist/lib/errors.d.ts +30 -0
package/dist/lib/errors.d.ts.map +1 -1
package/dist/lib/errors.js +55 -0
package/dist/lib/help-text.js +1 -1
package/dist/lib/parse-args.d.ts.map +1 -1
package/dist/lib/parse-args.js +17 -4
package/dist/lib/remix-config.d.ts +75 -0
package/dist/lib/remix-config.d.ts.map +1 -0
package/dist/lib/remix-config.js +411 -0
package/dist/lib/reporter.js +1 -1
package/dist/lib/route-map.js +13 -33
package/package.json +13 -7
package/schema/remix.json +242 -0
package/src/lib/app-root.ts +46 -0
package/src/lib/cli-context.ts +17 -0
package/src/lib/cli.ts +41 -6
package/src/lib/commands/db.ts +377 -0
package/src/lib/commands/doctor.ts +27 -329
package/src/lib/commands/help.ts +10 -1
package/src/lib/commands/test.ts +453 -12
package/src/lib/completion.ts +321 -6
package/src/lib/controller-files.ts +0 -38
package/src/lib/controller-ownership.ts +50 -203
package/src/lib/database-command.ts +31 -0
package/src/lib/doctor/controller-findings.ts +30 -47
package/src/lib/doctor/controllers.ts +2 -6
package/src/lib/doctor/project.ts +0 -236
package/src/lib/doctor/run.ts +311 -0
package/src/lib/doctor/types.ts +6 -5
package/src/lib/errors.ts +65 -0
package/src/lib/parse-args.ts +19 -3
package/src/lib/remix-config.ts +639 -0
package/src/lib/route-map.ts +11 -48
package/template/.agents/skills/remix/SKILL.md +38 -27
package/template/.agents/skills/remix/references/assets-and-browser-modules.md +54 -11
package/template/.agents/skills/remix/references/auth-and-sessions.md +5 -5
package/template/.agents/skills/remix/references/data-and-validation.md +15 -15
package/template/.agents/skills/remix/references/hydration-frames-navigation.md +63 -9
package/template/.agents/skills/remix/references/middleware-and-server.md +68 -6
package/template/.agents/skills/remix/references/mixins-styling-events.md +2 -0
package/template/.agents/skills/remix/references/routing-and-controllers.md +8 -8
package/template/.agents/skills/remix/references/testing-patterns.md +19 -18
package/template/AGENTS.md +6 -3
package/template/README.md +6 -3
package/template/app/actions/controller.tsx +1 -1
package/template/app/{ui → actions}/document.tsx +7 -5
package/template/app/{ui/scaffold-home-page.tsx → actions/home-page.tsx} +1 -2
package/template/app/actions/public/entry.ts +48 -0
package/template/app/{assets → actions/public}/prompt-button.tsx +29 -25
package/template/app/assets.ts +15 -2
package/template/app/middleware/render.tsx +8 -2
package/template/hmr.ts +46 -0
package/template/package.json +1 -0
package/template/server.ts +8 -1
package/template/tsconfig.json +1 -1
package/dist/lib/doctor/controller-fix-plans.d.ts +0 -4
package/dist/lib/doctor/controller-fix-plans.d.ts.map +0 -1
package/dist/lib/doctor/controller-fix-plans.js +0 -119
package/dist/lib/doctor/controller-placeholders.d.ts +0 -3
package/dist/lib/doctor/controller-placeholders.d.ts.map +0 -1
package/dist/lib/doctor/controller-placeholders.js +0 -52
package/src/lib/doctor/controller-fix-plans.ts +0 -168
package/src/lib/doctor/controller-placeholders.ts +0 -70
package/template/app/assets/entry.ts +0 -17

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

@@ -7,11 +7,12 @@ How server-rendered UI becomes interactive in the browser, and how the page upda
 - Marking a component for client-side hydration with `clientEntry`
 - Booting the client runtime with `run`
 - Streaming server content into a region of the page with `<Frame>` and reloading those regions
+- Handling browser HMR updates for hydrated entries
 - Triggering Navigation API transitions with `navigate(...)` or `link(...)`
 - Server rendering with `renderToStream` or `renderToString`
 - Managing the document `<head>`
-For component-local state and updates, see `component-model.md`. For host-element behavior and events, see `mixins-styling-events.md`.
+For component-local state and updates, see `component-model.md`. For host-element behavior and events, see `mixins-styling-events.md`. For browser asset HMR setup, see `assets-and-browser-modules.md`.
 ## Server First, Then Hydrate
@@ -75,9 +76,15 @@ let stream = renderToStream(<App />, {
       throw new Error(`Unable to resolve client entry export for ${entryId}`)
     }
+    let [href, preloads] = await Promise.all([
+      assetServer.getHref(entryId),
+      assetServer.getPreloads(entryId),
+    ])
     return {
-      href: await assetServer.getHref(entryId),
+      href,
       exportName,
+      preloads,
     }
   },
 })
@@ -89,26 +96,46 @@ On the server, `clientEntry` components render like any other component. The ser
 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'
-let app = run({
+const app = run({
   async loadModule(moduleUrl, exportName) {
     let mod = await import(moduleUrl)
     return mod[exportName]
   },
-  async resolveFrame(src, signal, target) {
-    let headers = new Headers({ accept: 'text/html' })
-    if (target) headers.set('x-remix-target', target)
-    let response = await fetch(src, { headers, signal })
+  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)
 })
@@ -119,7 +146,7 @@ await app.ready()
 ### `run` options
 - **`loadModule(moduleUrl, exportName)`** (required) — return the component function for each client entry. Typically uses dynamic `import()`.
-- **`resolveFrame(src, signal, target)`** (optional) — called when a `<Frame>` loads or reloads content. `target` is available when frame targeting matters.
+- **`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`.
 ### `app` methods
@@ -129,6 +156,19 @@ await app.ready()
 `app` is an `EventTarget` that emits `error` events from any hydrated component.
+## Browser HMR Updates
+When `remix/node-hmr` reports a server update, reload the top frame to apply the latest server-rendered document while preserving browser state:
+```tsx
+if (import.meta.hot) {
+  import.meta.hot.on('server:update', async () => {
+    await app.ready()
+    await app.frames.top.reload()
+  })
+}
+```
 ## Frames
 A `<Frame>` renders server content into the page. Frames stream after the initial HTML, nest inside other frames, contain client entries, and can be reloaded without full page navigation.
@@ -175,6 +215,20 @@ handle.frames.top.reload()
 When a frame reloads, matching DOM nodes are updated in place. Client entries receive updated props while preserving their local component state.
+### 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.
+- 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.
+- 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.
 ### Nested frames
 Frames can nest. Each frame owns its own DOM region and hydrates client entries independently. During SSR, `handle.frame.src` points at the frame being rendered, while `handle.frames.top.src` stays fixed at the outer document URL.
@@ -238,7 +292,7 @@ navigate('/dashboard', { history: 'replace' })
 Options: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
-Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-document`.
+Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-history`, `rmx-reset-scroll`, `rmx-document`.
 ## Head Management

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

@@ -8,8 +8,9 @@ How to compose the request lifecycle and bridge the router to a runtime. Read th
 - Writing custom middleware that sets typed context values
 - Adding fast-exit handling (static files, CORS preflights) versus request-enriching layers (sessions, auth, data loading)
 - Choosing when to keep the generated Node server versus switching server adapters
+- Running the app server under development HMR
-For data and persistence specifics, see `data-and-validation.md`. For session and auth specifics, see `auth-and-sessions.md`.
+For data and persistence specifics, see `data-and-validation.md`. For session and auth specifics, see `auth-and-sessions.md`. For browser asset HMR, see `assets-and-browser-modules.md`.
 ## Middleware Stack
@@ -64,8 +65,9 @@ let router = createRouter({ middleware })
 ### 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 `public/`
+- 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
+- `public/` directories inside `app/` hold browser-reachable source for the asset server
 ### Ordering notes
@@ -80,6 +82,7 @@ let router = createRouter({ middleware })
 - **Session-backed HTML app** -> `compression()`, `staticFiles()`, optional `cop()`, `formData()`, `methodOverride()`, `session()`, optional `csrf()`, `asyncContext()`, `auth({ schemes })`
 - **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()`
 ### Middleware with options
@@ -116,11 +119,11 @@ Use `context.set(key, value)` to add typed values accessible downstream via `con
 ```typescript
 import type { Middleware } from 'remix/router'
-import { Database } from 'remix/data-table'
+import { databaseContext } from '~/middleware/database.ts'
 export function loadDatabase(): Middleware {
   return async (context, next) => {
-    context.set(Database, db)
+    context.set(databaseContext, db)
     return next()
   }
 }
@@ -150,11 +153,11 @@ export function requireAdmin(): Middleware {
 // app/utils/context.ts
 import { getContext } from 'remix/middleware/async-context'
 import { Auth } from 'remix/middleware/auth'
-import { Database } from 'remix/data-table'
+import { databaseContext } from '~/middleware/database.ts'
 import { Session } from 'remix/session'
 export function getCurrentDb() {
-  return getContext().get(Database)
+  return getContext().get(databaseContext)
 }
 export function getCurrentSession() {
@@ -214,3 +217,62 @@ Prefer inline arrays for `middleware` options. Use `RouterContext<typeof 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.
 Use `remix/node-fetch-server` when you want to keep owning a standard Node `http`, `https`, or `http2` server directly.
+## Development HMR
+Treat HMR as an optional mode for rapid UI edits. Keep HMR supervision out of normal app code:
+put the real app server in `server.ts`, keep the `dev` script running it directly (usually with
+Node's watch mode), then add a development-only `hmr.ts` behind an `hmr` script when the project
+benefits from HMR.
+```typescript
+// hmr.ts
+import * as http from 'node:http'
+import { createFetchProxy } from 'remix/fetch-proxy'
+import { createHmrReadyFetch, run } from 'remix/node-hmr'
+import { createRequestListener } from 'remix/node-fetch-server'
+const hmrProxyPort = 44100
+const hmrEventPort = 44101
+const appPort = 44102
+const hmrRunner = run('./server.ts', {
+  env: {
+    ...process.env,
+    PORT: String(appPort),
+    HMR_PROXY_PORT: String(hmrProxyPort),
+  },
+  nodeArgs: ['--import', 'remix/node-tsx', '--import', 'remix/ui-hmr/node'],
+  browserHmrChannel: { port: hmrEventPort },
+})
+let proxyFetch = createFetchProxy(`http://127.0.0.1:${appPort}`, {
+  xForwardedHeaders: true,
+})
+let server = http.createServer(createRequestListener(createHmrReadyFetch(hmrRunner, proxyFetch)))
+server.listen(hmrProxyPort, '127.0.0.1')
+```
+Keep `browserHmrChannel.port` stable so browser HMR clients can reconnect to the same event channel if the dev server is manually restarted.
+Use a stable public proxy when browser requests may happen while the child server is restarting. `createHmrReadyFetch()` waits for the active child generation before forwarding requests and retries safe unavailable responses when the child changes during a request.
+In the child `server.ts`, report readiness after the server is listening:
+```typescript
+server.listen(port, () => {
+  if (process.env.REMIX_NODE_HMR) {
+    import('remix/node-hmr/runtime').then((nodeHmr) => nodeHmr.emitServerReady())
+  }
+})
+```
+Rules:
+- Guard `remix/node-hmr/runtime` imports with `process.env.REMIX_NODE_HMR`.
+- Use `--import remix/ui-hmr/node` only when server-rendered Remix UI component modules should hot update.
+- Keep the default development and production startup paths independent from `hmr.ts`.
+- Close the public server and `hmrRunner` during `SIGINT` and `SIGTERM` shutdown.

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

@@ -115,6 +115,8 @@ 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.
 ## Native press and keyboard interactions
 Use native DOM events directly with `on(...)`. For buttons and links, `click` already includes keyboard activation when the element has the right semantics:

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

@@ -103,7 +103,7 @@ export const search = createAction(routes.search, {
 The handler receives a context object with:
-- `get(key)` — read a value set by middleware (e.g. `get(Database)`, `get(Session)`, `get(Auth)`)
+- `get(key)` — read a value set by middleware (e.g. `get(databaseContext)`, `get(Session)`, `get(Auth)`)
 - `params` — typed route params
 - `url` — the request URL
 - `request` — the raw `Request`
@@ -132,7 +132,7 @@ For pages, render a component tree and return the resulting `Response`:
 ```typescript
 async handler({ get }) {
-  let db = get(Database)
+  let db = get(databaseContext)
   let books = await db.findMany(books, { orderBy: ['id', 'asc'] })
   return render(<IndexPage books={books} />)
 }
@@ -152,7 +152,7 @@ async create({ get }) {
     return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
   }
-  let db = get(Database)
+  let db = get(databaseContext)
   let book = await db.create(books, parsed.value)
   return redirect(routes.books.show.href({ slug: book.slug }), 303)
@@ -167,7 +167,7 @@ For expected failures — validation, conflict, not found — return a `Response
 ```typescript
 async show({ get, params }) {
-  let db = get(Database)
+  let db = get(databaseContext)
   let book = await db.find(books, params.bookId)
   if (!book) return new Response('Not Found', { status: 404 })
   return render(<ShowPage book={book} />)
@@ -208,7 +208,7 @@ If you find yourself returning JSON for what is really a browser form submission
 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.
+Configure `RouterTypes.context` with your app context in the router module, then use `createController()` so `get(databaseContext)`, `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'
@@ -218,13 +218,13 @@ import { routes } from '../routes.ts'
 export default createController(routes.books, {
   actions: {
     async index({ get }) {
-      let db = get(Database)
+      let db = get(databaseContext)
       let items = await db.findMany(books, { orderBy: ['id', 'asc'] })
       return render(<IndexPage items={items} />)
     },
     async show({ get, params }) {
-      let db = get(Database)
+      let db = get(databaseContext)
       let book = await db.find(books, params.bookId)
       if (!book) return new Response('Not Found', { status: 404 })
       return render(<ShowPage book={book} />)
@@ -359,4 +359,4 @@ declare module 'remix/router' {
 }
 ```
-This gives typed `context.get(Database)`, `context.get(Session)`, `context.get(Auth)`, etc.
+This gives typed `context.get(databaseContext)`, `context.get(Session)`, `context.get(Auth)`, etc.

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

@@ -70,28 +70,29 @@ try {
 ## 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,
+Configure discovery and coverage in the `test` section of `remix.json` or with CLI flags:
+```jsonc
+{
+  "$schema": "https://remix.run/schemas/remix.json",
+  "test": {
+    "files": ["**/*.test{,.e2e}.{ts,tsx}"],
+    "e2eFiles": ["**/*.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.
+Use `remix test --coverage` to enable coverage with defaults. Use `exclude` when discovery would otherwise enter generated output, symlinked workspaces, or other paths that should not produce tests.
 ## Component Tests

package/template/AGENTS.md CHANGED Viewed

@@ -6,6 +6,8 @@ This app was scaffolded with `remix new`. Use these conventions when continuing
 ```sh
 npm i
+npm run dev
+npm run hmr
 npm run start
 npm test
 npm run typecheck
@@ -18,12 +20,13 @@ Refer to ./.agents/skills/remix/SKILL.md
 ## Starter Layout
 - `app/actions/controller.tsx` owns the top-level route actions
-- `app/routes.ts` defines the route contract
+- `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/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
+- Root `public/` contains static files served unchanged from the app root
 ## Route Ownership

package/template/README.md CHANGED Viewed

@@ -5,12 +5,13 @@ 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/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/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.
+- Root `public/` contains static files served unchanged from the app root.
 ## Growing The App
@@ -23,6 +24,8 @@ A minimal Remix application starter with a home page.
 ```sh
 npm i
+npm run dev
+npm run hmr
 npm run start
 npm test
 npm run typecheck

package/template/app/actions/controller.tsx CHANGED Viewed

@@ -2,7 +2,7 @@ import { createController } from 'remix/router'
 import { assetServer } from '../assets.ts'
 import { routes } from '../routes.ts'
-import { HomePage } from '../ui/scaffold-home-page.tsx'
+import { HomePage } from './home-page.tsx'
 export default createController(routes, {
   actions: {

package/template/app/{ui → actions}/document.tsx RENAMED Viewed

@@ -1,7 +1,7 @@
 import type { Handle, RemixNode } from 'remix/ui'
 import { css } from 'remix/ui'
-import { routes } from '../routes.ts'
+import { entryHref, entryPreloads } from '../assets.ts'
 export interface DocumentProps {
   children?: RemixNode
@@ -20,14 +20,16 @@ export function Document(handle: Handle<DocumentProps>) {
         <head>
           <meta charSet="utf-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1" />
+          <meta name="color-scheme" content="light dark" />
           <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
           <title>{title}</title>
           {head}
+          {entryPreloads.map((href) => (
+            <link key={href} rel="modulepreload" href={href} />
+          ))}
+          <script type="module" src={entryHref}></script>
         </head>
-        <body mix={css({ margin: 0 })}>
-          {children}
-          <script type="module" src={routes.assets.href({ path: 'app/assets/entry.ts' })}></script>
-        </body>
+        <body mix={css({ margin: 0 })}>{children}</body>
       </html>
     )
   }

package/template/app/{ui/scaffold-home-page.tsx → actions/home-page.tsx} RENAMED Viewed

@@ -2,8 +2,8 @@
 import type { Handle, RemixNode } from 'remix/ui'
 import { css } from 'remix/ui'
-import { PromptButton } from '../assets/prompt-button.tsx'
 import { Document } from './document.tsx'
+import { PromptButton } from './public/prompt-button.tsx'
 const FONT_STACK =
   "'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace"
@@ -66,7 +66,6 @@ export function HomePage() {
 function HomeHead() {
   return () => (
     <>
-      <meta name="color-scheme" content="light dark" />
       <link rel="preconnect" href="https://fonts.googleapis.com" />
       <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
       <link

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

@@ -0,0 +1,48 @@
+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>`
+    }
+    if (response.body) return response.body
+    return await response.text()
+  },
+})
+if (import.meta.hot) {
+  import.meta.hot.on('server:update', async () => {
+    try {
+      await app.ready()
+      await app.frames.top.reload()
+    } catch (error) {
+      console.error('Error reloading top frame on server update', error)
+    }
+  })
+}
+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 → actions/public}/prompt-button.tsx RENAMED Viewed

@@ -28,11 +28,6 @@ export const PromptButton = clientEntry(
       return (
         <button
           type="button"
-          className={state}
-          style={{
-            background: active ? 'var(--surface-4)' : undefined,
-            color: active ? 'var(--brand-blue)' : undefined,
-          }}
           mix={[
             buttonStyle,
             on('click', async (_event, signal) => {
@@ -67,32 +62,23 @@ export const PromptButton = clientEntry(
               await handle.update()
             }),
           ]}
+          style={
+            active
+              ? {
+                  background: 'var(--surface-4)',
+                  color: 'var(--brand-blue)',
+                }
+              : undefined
+          }
         >
           <span aria-hidden="true" mix={iconSlotStyle}>
             <CopyIcon />
           </span>
-          <span
-            mix={css({
-              alignItems: 'center',
-              display: 'flex',
-              fontSize: '14px',
-              flex: '1 1 0',
-              lineHeight: 1.5,
-              minWidth: 0,
-              position: 'relative',
-              transition: 'opacity 180ms ease',
-            })}
-            style={{ opacity: state === 'resetting' ? 0 : undefined }}
-          >
+          <span mix={labelSlotStyle} style={{ opacity: state === 'resetting' ? 0 : 1 }}>
             <span
               aria-hidden={state === 'idle' ? true : undefined}
-              style={{
-                alignItems: 'center',
-                display: 'flex',
-                inset: 0,
-                position: 'absolute',
-                visibility: state === 'idle' ? 'hidden' : 'visible',
-              }}
+              mix={statusLabelStyle}
+              style={{ visibility: state === 'idle' ? 'hidden' : 'visible' }}
             >
               {label}
             </span>
@@ -148,6 +134,24 @@ const buttonStyle = css({
   },
 })
+const labelSlotStyle = css({
+  alignItems: 'center',
+  display: 'flex',
+  fontSize: '14px',
+  flex: '1 1 0',
+  lineHeight: 1.5,
+  minWidth: 0,
+  position: 'relative',
+  transition: 'opacity 180ms ease',
+})
+const statusLabelStyle = css({
+  alignItems: 'center',
+  display: 'flex',
+  inset: 0,
+  position: 'absolute',
+})
 const iconSlotStyle = css({
   flex: '0 0 24px',
   width: '24px',

package/template/app/assets.ts CHANGED Viewed

@@ -1,8 +1,10 @@
 import { createAssetServer } from 'remix/assets'
+import { uiHmr } from 'remix/ui-hmr/assets'
 const rootDir = process.cwd()
 const nodeEnv = process.env.NODE_ENV ?? 'development'
 const isDevelopment = nodeEnv === 'development'
+const isHmr = Boolean(isDevelopment && process.env.REMIX_NODE_HMR)
 export const assetServer = createAssetServer({
   basePath: '/assets',
@@ -11,8 +13,19 @@ export const assetServer = createAssetServer({
     'app/*path': 'app/*path',
     'node_modules/*path': 'node_modules/*path',
   },
-  allow: ['app/assets/**', 'node_modules/**'],
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  allowPackages: ['remix'],
+  denyFiles: ['app/**/*.test.*'],
   sourceMaps: isDevelopment ? 'external' : undefined,
   minify: !isDevelopment,
-  watch: false,
+  watch: isDevelopment,
+  hmr: isHmr
+    ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+    : 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)