@remix-run/cli 0.2.0 → 0.3.1

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'
 

package/{bootstrap → template}/app/assets.ts

@@ -1,13 +1,15 @@
 import { createAssetServer } from 'remix/assets'
 
-export const assets = createAssetServer({
+const rootDir = process.cwd()
+
+export const assetServer = createAssetServer({
   basePath: '/assets',
-  rootDir: process.cwd(),
+  rootDir,
   fileMap: {
     'app/*path': 'app/*path',
     'node_modules/*path': 'node_modules/*path',
   },
-  allow: ['app/assets/**', 'app/ui/prompt-button.tsx', 'node_modules/**'],
+  allow: ['app/assets/**', 'node_modules/**'],
   deny: ['app/**/*.server.*'],
   sourceMaps: process.env.NODE_ENV === 'development' ? 'external' : undefined,
   scripts: {

package/template/app/middleware/render.tsx

@@ -0,0 +1,44 @@
+import * as path from 'node:path'
+
+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 }) =>
+      function render(node: RemixNode, init?: ResponseInit) {
+        let stream = renderToStream(node, {
+          signal: request.signal,
+          // 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)
+      },
+  )
+}
+
+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('')
+}

package/template/app/router.ts

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

package/{bootstrap → template}/app/routes.ts

@@ -1,7 +1,6 @@
-import { get, route } from 'remix/fetch-router/routes'
+import { get, route } from 'remix/routes'
 
 export const routes = route({
   assets: get('/assets/*path'),
   home: '/',
-  auth: '/auth',
 })

package/{bootstrap → template}/app/ui/document.tsx

@@ -1,26 +1,33 @@
-import type { RemixNode } from 'remix/ui'
+import { css, type RemixNode } from 'remix/ui'
 
 import { routes } from '../routes.ts'
 
 export interface DocumentProps {
   children?: RemixNode
+  head?: RemixNode
   title?: string
 }
 
-const DEFAULT_TITLE = decodeURIComponent('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%')
+const DEFAULT_TITLE = readAppDisplayName('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%')
 
 export function Document() {
-  return ({ title = DEFAULT_TITLE, children }: DocumentProps) => (
+  return ({ children, head, title = DEFAULT_TITLE }: DocumentProps) => (
     <html lang="en">
       <head>
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
         <title>{title}</title>
+        {head}
       </head>
-      <body>
+      <body mix={css({ margin: 0 })}>
         {children}
         <script type="module" src={routes.assets.href({ path: 'app/assets/entry.ts' })}></script>
       </body>
     </html>
   )
 }
+
+function readAppDisplayName(value: string): string {
+  return value.startsWith('%%') ? 'Remix App' : decodeURIComponent(value)
+}

package/{bootstrap → template}/app/ui/scaffold-home-page.tsx

@@ -1,31 +1,16 @@
-// Delete this file and put your own home page in app/controllers/home.tsx
+// Delete this file and put your own home page in app/actions/controller.tsx
 import { css, type RemixNode } from 'remix/ui'
 
-import { PromptButton } from './prompt-button.tsx'
-import { routes } from '../routes.ts'
-
-const APP_DISPLAY_NAME = decodeURIComponent('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%')
+import { PromptButton } from '../assets/prompt-button.tsx'
+import { Document } from './document.tsx'
 
 const FONT_STACK =
   "'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace"
 
 export function HomePage() {
   return () => (
-    <html lang="en">
-      <head>
-        <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width,initial-scale=1" />
-        <meta name="color-scheme" content="light dark" />
-        <title>Welcome to {APP_DISPLAY_NAME}</title>
-        <link rel="preconnect" href="https://fonts.googleapis.com" />
-        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
-        <link
-          rel="stylesheet"
-          href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
-        />
-        <script type="module" src={routes.assets.href({ path: 'app/assets/entry.ts' })}></script>
-      </head>
-      <body
+    <Document head={<HomeHead />}>
+      <main
         mix={css({
           // Light-mode design tokens (default).
           '--surface-0': '#dee2e6',
@@ -58,7 +43,7 @@ export function HomePage() {
           justifyContent: 'center',
         })}
       >
-        <main
+        <div
           mix={css({
             width: '100%',
             maxWidth: '820px',
@@ -71,9 +56,23 @@ export function HomePage() {
           <Masthead />
           <Columns />
           <Footer />
-        </main>
-      </body>
-    </html>
+        </div>
+      </main>
+    </Document>
+  )
+}
+
+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
+        rel="stylesheet"
+        href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
+      />
+    </>
   )
 }
 
@@ -133,8 +132,8 @@ function Columns() {
 
 function GetStartedCard() {
   return () => (
-    <div mix={css({ ...CARD_STYLES, flex: '0 0 auto' })}>
-      <h2 mix={css(CARD_HEADER_STYLES)}>Get started</h2>
+    <div mix={[cardStyle, css({ flex: '0 0 auto' })]}>
+      <h2 mix={cardHeaderStyle}>Get started</h2>
       <ul
         mix={css({
           listStyle: 'none',
@@ -147,7 +146,7 @@ function GetStartedCard() {
         })}
       >
         <li>
-          <CardLink href="https://remix.run/docs" icon={<AtomIcon />} label="Remix Docs" />
+          <CardLink href="https://api.remix.run" icon={<AtomIcon />} label="Remix API" />
         </li>
         <li>
           <CardLink
@@ -164,14 +163,16 @@ function GetStartedCard() {
 function CodingWithAiCard() {
   return () => (
     <div
-      mix={css({
-        ...CARD_STYLES,
-        width: '540px',
-        justifyContent: 'center',
-        '@media (max-width: 720px)': { width: '100%' },
-      })}
+      mix={[
+        cardStyle,
+        css({
+          width: '540px',
+          justifyContent: 'center',
+          '@media (max-width: 720px)': { width: '100%' },
+        }),
+      ]}
     >
-      <h2 mix={css(CARD_HEADER_STYLES)}>Coding with AI?</h2>
+      <h2 mix={cardHeaderStyle}>Coding with AI?</h2>
       <div
         mix={css({
           width: '100%',
@@ -332,7 +333,7 @@ function Footer() {
   )
 }
 
-const CARD_STYLES = {
+const cardStyle = css({
   background: 'var(--surface-3)',
   borderRadius: '20px',
   padding: '32px 16px 16px',
@@ -340,9 +341,9 @@ const CARD_STYLES = {
   flexDirection: 'column',
   alignItems: 'center',
   gap: '32px',
-} as const
+})
 
-const CARD_HEADER_STYLES = {
+const cardHeaderStyle = css({
   margin: 0,
   width: '100%',
   padding: '0 16px',
@@ -354,7 +355,7 @@ const CARD_HEADER_STYLES = {
   textTransform: 'uppercase',
   letterSpacing: '0.1em',
   color: 'var(--text-primary)',
-} as const
+})
 
 // ----- SVG icons -----
 // Inline so the page is fully self-contained with no external icon assets.

package/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+db/*.sqlite
+tmp/
+.DS_Store

package/{bootstrap → template}/package.json

@@ -1,19 +1,18 @@
 {
-  "name": "remix-bootstrap-template",
+  "name": "remix-template",
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "tsx watch server.ts",
-    "start": "tsx server.ts",
-    "test": "tsx --test",
+    "dev": "node --watch --import remix/node-tsx server.ts",
+    "start": "node --import remix/node-tsx server.ts",
+    "test": "node --import remix/node-tsx --test",
     "typecheck": "tsc --noEmit"
   },
   "engines": {
     "node": ">=24.3.0"
   },
   "dependencies": {
-    "remix": "workspace:^",
-    "tsx": "catalog:"
+    "remix": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "catalog:",

package/template/public/favicon.svg

@@ -0,0 +1,11 @@
+<svg width="144" height="144" viewBox="0 0 144 144" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="144" height="144" rx="72" fill="black"/>
+<g clip-path="url(#clip0_2008_2428)">
+<path d="M102.763 51.2382L102.762 51.2391V51.2401C113.767 51.2402 121.369 56.1787 119.744 62.2714L118.643 66.3973C117.017 72.4901 106.778 77.4286 95.7734 77.4286H94.6475L117.765 92.5868H80.6504L61.9629 78.163C61.2148 77.6833 60.3465 77.4286 59.459 77.4286H28.2197L31.1631 66.3954H85.8799C87.9367 66.3954 89.8519 65.4721 90.1562 64.3329H90.1572C90.4613 63.1935 89.0394 62.2694 86.9814 62.2694H32.2646L35.207 51.2382H102.763ZM54.1865 81.2362C55.2231 81.2363 55.9785 82.2245 55.71 83.2303L53.2139 92.5858H24.1768L27.2041 81.2362H54.1865Z" fill="white"/>
+</g>
+<defs>
+<clipPath id="clip0_2008_2428">
+<rect width="96" height="41.5862" fill="white" transform="translate(24 51.2069)"/>
+</clipPath>
+</defs>
+</svg>

package/template/server.ts

@@ -0,0 +1,38 @@
+import * as http from 'node:http'
+import { createRequestListener } from 'remix/node-fetch-server'
+
+import { router } from './app/router.ts'
+
+const port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 44100
+
+const server = http.createServer(
+  createRequestListener(async (request) => {
+    try {
+      return await router.fetch(request)
+    } catch (error) {
+      if (!(request.signal.aborted && error === request.signal.reason)) {
+        console.error(error)
+      }
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }),
+)
+
+server.listen(port, () => {
+  console.log(`Server listening on http://localhost:${port}`)
+})
+
+let shuttingDown = false
+
+function shutdown() {
+  if (shuttingDown) {
+    return
+  }
+
+  shuttingDown = true
+  server.close(() => process.exit(0))
+  server.closeAllConnections()
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)

package/{bootstrap → template}/tsconfig.json

@@ -3,12 +3,13 @@
     "strict": true,
     "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "types": ["node"],
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "target": "ESNext",
     "allowImportingTsExtensions": true,
     "rewriteRelativeImportExtensions": true,
     "verbatimModuleSyntax": true,
+    "isolatedModules": true,
     "skipLibCheck": true,
     "jsx": "react-jsx",
     "jsxImportSource": "remix/ui",

package/bootstrap/README.md

@@ -1,27 +0,0 @@
-# %%RMX_APP_DISPLAY_NAME%%
-
-A minimal Remix application starter with a home page and an auth page.
-
-## Starter Shape
-
-- `app/controllers/home.tsx` owns the home page.
-- `app/controllers/auth.tsx` owns the auth page.
-- `app/routes.ts` defines the route contract.
-- `app/router.ts` wires routes to handlers.
-- `app/ui/` holds the shared document and layout wrappers.
-- `app/utils/render.tsx` centralizes HTML response rendering.
-
-## Growing The App
-
-- Start with flat route files and only introduce route folders when a route needs multiple actions or route-owned modules.
-- Add directories like `app/data/`, `app/middleware/`, `public/`, 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/bootstrap/app/assets/entry.ts

@@ -1,19 +0,0 @@
-import { run } from 'remix/ui'
-
-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, {
-      credentials: 'same-origin',
-      headers,
-      signal,
-    })
-    return response.body ?? response.text()
-  },
-})

package/bootstrap/app/controllers/auth.tsx

@@ -1,21 +0,0 @@
-import type { BuildAction } from 'remix/fetch-router'
-
-import type { routes } from '../routes.ts'
-import { Layout } from '../ui/layout.tsx'
-import { render } from '../utils/render.tsx'
-
-export const auth: BuildAction<'GET', typeof routes.auth> = {
-  handler({ request }) {
-    return render(<AuthPage />, request)
-  },
-}
-
-function AuthPage() {
-  return () => (
-    <Layout title="Auth">
-      <h1>Auth</h1>
-      <p>Use this route to start building sign-in, sign-up, and session flows.</p>
-      <p>Keep it as a flat file until the route needs multiple actions or route-owned modules.</p>
-    </Layout>
-  )
-}

package/bootstrap/app/controllers/home.tsx

@@ -1,11 +0,0 @@
-import type { BuildAction } from 'remix/fetch-router'
-
-import type { routes } from '../routes.ts'
-import { HomePage } from '../ui/scaffold-home-page.tsx'
-import { render } from '../utils/render.tsx'
-
-export const home: BuildAction<'GET', typeof routes.home> = {
-  handler({ request }) {
-    return render(<HomePage />, request)
-  },
-}

package/bootstrap/app/router.ts

@@ -1,16 +0,0 @@
-import { createRouter } from 'remix/fetch-router'
-
-import { assets } from './assets.ts'
-import { auth } from './controllers/auth.tsx'
-import { home } from './controllers/home.tsx'
-import { routes } from './routes.ts'
-
-export const router = createRouter()
-
-router.get(routes.assets, async ({ request }) => {
-  let response = await assets.fetch(request)
-  return response ?? new Response('Not Found', { status: 404 })
-})
-
-router.map(routes.home, home)
-router.map(routes.auth, auth)

package/bootstrap/app/ui/layout.tsx

@@ -1,22 +0,0 @@
-import type { RemixNode } from 'remix/ui'
-
-import { routes } from '../routes.ts'
-import { Document } from './document.tsx'
-
-export interface LayoutProps {
-  children?: RemixNode
-  title?: string
-}
-
-export function Layout() {
-  return ({ title, children }: LayoutProps) => (
-    <Document title={title}>
-      <header>
-        <nav>
-          <a href={routes.home.href()}>Home</a> <a href={routes.auth.href()}>Auth</a>
-        </nav>
-      </header>
-      <main>{children}</main>
-    </Document>
-  )
-}