npm - @remix-run/cli - Versions diffs - 0.1.0 → 0.2.0 - Mend

@remix-run/cli 0.1.0 → 0.2.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 (56) hide show

package/README.md +0 -3
package/bootstrap/.agents/skills/remix/SKILL.md +501 -0
package/bootstrap/.agents/skills/remix/references/animate-elements.md +195 -0
package/bootstrap/.agents/skills/remix/references/assets-and-browser-modules.md +122 -0
package/bootstrap/.agents/skills/remix/references/auth-and-sessions.md +420 -0
package/bootstrap/.agents/skills/remix/references/component-model.md +282 -0
package/bootstrap/.agents/skills/remix/references/create-mixins.md +158 -0
package/bootstrap/.agents/skills/remix/references/data-and-validation.md +363 -0
package/bootstrap/.agents/skills/remix/references/hydration-frames-navigation.md +297 -0
package/bootstrap/.agents/skills/remix/references/middleware-and-server.md +243 -0
package/bootstrap/.agents/skills/remix/references/mixins-styling-events.md +213 -0
package/bootstrap/.agents/skills/remix/references/routing-and-controllers.md +324 -0
package/bootstrap/.agents/skills/remix/references/testing-patterns.md +156 -0
package/bootstrap/AGENTS.md +4 -0
package/bootstrap/app/assets/entry.ts +19 -0
package/bootstrap/app/assets.ts +18 -0
package/bootstrap/app/controllers/auth.tsx +2 -2
package/bootstrap/app/controllers/home.tsx +3 -18
package/bootstrap/app/router.ts +6 -0
package/bootstrap/app/routes.ts +2 -1
package/bootstrap/app/ui/document.tsx +6 -1
package/bootstrap/app/ui/prompt-button.tsx +162 -0
package/bootstrap/app/ui/scaffold-home-page.tsx +526 -0
package/bootstrap/app/utils/render.tsx +22 -3
package/bootstrap/server.ts +13 -13
package/bootstrap/tsconfig.json +0 -1
package/dist/lib/cli.d.ts.map +1 -1
package/dist/lib/cli.js +7 -10
package/dist/lib/commands/help.d.ts.map +1 -1
package/dist/lib/commands/help.js +9 -33
package/dist/lib/commands/test.d.ts +1 -1
package/dist/lib/commands/test.d.ts.map +1 -1
package/dist/lib/commands/test.js +8 -4
package/dist/lib/completion.d.ts.map +1 -1
package/dist/lib/completion.js +3 -101
package/dist/lib/errors.d.ts +0 -6
package/dist/lib/errors.d.ts.map +1 -1
package/dist/lib/errors.js +0 -11
package/package.json +3 -4
package/src/lib/cli.ts +7 -11
package/src/lib/commands/help.ts +9 -43
package/src/lib/commands/test.ts +10 -4
package/src/lib/completion.ts +3 -146
package/src/lib/errors.ts +0 -12
package/dist/lib/commands/skills.d.ts +0 -6
package/dist/lib/commands/skills.d.ts.map +0 -1
package/dist/lib/commands/skills.js +0 -222
package/dist/lib/skills-cache.d.ts +0 -19
package/dist/lib/skills-cache.d.ts.map +0 -1
package/dist/lib/skills-cache.js +0 -89
package/dist/lib/skills.d.ts +0 -30
package/dist/lib/skills.d.ts.map +0 -1
package/dist/lib/skills.js +0 -441
package/src/lib/commands/skills.ts +0 -306
package/src/lib/skills-cache.ts +0 -140
package/src/lib/skills.ts +0 -706

package/bootstrap/.agents/skills/remix/references/hydration-frames-navigation.md ADDED Viewed

@@ -0,0 +1,297 @@
+# Hydration, Frames, and Navigation
+## What This Covers
+How server-rendered UI becomes interactive in the browser, and how the page updates without a full
+navigation. Read this when the task involves:
+- 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
+- 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`.
+## Server First, Then Hydrate
+Make the server route correct before adding `clientEntry(...)`. A POST should already do the right
+thing on its own — return HTML, a redirect, or an error response — and a GET should already render
+the page the user expects. `clientEntry` exists to layer interactivity on top of UI that already
+works without it.
+When server state changes after a mutation, prefer reloading a `<Frame>` when the UI region already
+maps cleanly to a server-rendered route. Frames re-fetch the same route, so the rendering logic
+stays in one place and the client does not need a parallel "state" API.
+```tsx
+on('submit', async (event, signal) => {
+  event.preventDefault()
+  await fetch(routes.cart.add.href(), {
+    method: 'POST',
+    body: new FormData(event.currentTarget),
+    signal,
+  })
+  if (signal.aborted) return
+  await handle.frames.get('cart-summary')?.reload()
+})
+```
+Use polling or a small JSON state endpoint when the data changes outside this page, or when a tiny
+shared widget would be heavier to model as a frame. Pick the lightest sync mechanism that preserves
+clear ownership of rendering logic.
+## Client Entries
+Use `clientEntry` to mark a component for client-side hydration. In source-served apps, prefer the
+source module's `import.meta.url` as the entry ID and let server rendering map it to the public
+asset URL:
+```tsx
+import { clientEntry, on, type Handle } from 'remix/ui'
+export const Counter = clientEntry(
+  import.meta.url,
+  function Counter(handle: Handle<{ initialCount: number; label: string }>) {
+    let count = handle.props.initialCount
+    return () => (
+      <div>
+        <span>
+          {handle.props.label}: {count}
+        </span>
+        <button
+          mix={on('click', () => {
+            count++
+            handle.update()
+          })}
+        >
+          +
+        </button>
+      </div>
+    )
+  },
+)
+```
+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:
+```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,
+    }
+  },
+})
+```
+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.
+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.
+## 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 { run } from 'remix/ui'
+let 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 })
+    return response.body ?? (await response.text())
+  },
+})
+app.addEventListener('error', (event) => {
+  console.error('Component error:', event.error)
+})
+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.
+### `app` methods
+- **`app.ready()`** — resolves when all initial client entries are hydrated
+- **`app.flush()`** — synchronously flushes all pending updates
+- **`app.dispose()`** — tears down all hydrated components
+`app` is an `EventTarget` that emits `error` events from any hydrated component.
+## 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.
+```tsx
+import { Frame } from 'remix/ui'
+function App() {
+  return () => (
+    <div>
+      <Frame src="/sidebar" fallback={<div>Loading...</div>} />
+      <Frame name="main" src="/main-content" />
+    </div>
+  )
+}
+```
+### Frame props
+- **`src`** (required) — URL to fetch the frame content from
+- **`fallback`** (optional) — content to show while loading; determines streaming behavior
+- **`name`** (optional) — registers the frame for lookup via `handle.frames.get(name)`
+- **`on`** (optional) — event handlers for events dispatched from the frame element
+### Blocking vs non-blocking
+- **Without `fallback`** (blocking) — the server waits for frame content before sending the initial
+  HTML chunk
+- **With `fallback`** (non-blocking) — the fallback renders immediately; real content streams in
+  later and replaces it
+### Reloading frames
+Client entries inside a frame can trigger a reload:
+```tsx
+// Reload the containing frame
+handle.frame.reload()
+// Reload an adjacent named frame
+await handle.frames.get('cart-summary')?.reload()
+// Reload the entire page/frame tree
+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.
+### 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.
+## Server Rendering
+### `renderToStream`
+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'
+let stream = renderToStream(<App />, {
+  frameSrc: request.url,
+  resolveFrame(src, target, context) {
+    let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
+    return fetchHtml(frameUrl)
+  },
+  onError(error) {
+    console.error(error)
+  },
+})
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/html; charset=utf-8' },
+})
+```
+Options:
+- **`frameSrc`** — seeds SSR frame state; populates `handle.frame.src` and `handle.frames.top.src`
+- **`topFrameSrc`** — overrides the root frame URL for nested frame renders (carry forward from
+  `resolveFrame` context)
+- **`resolveFrame(src, target, context)`** — return HTML string, `ReadableStream<Uint8Array>`, or a
+  promise of either. `context.currentFrameSrc` is the containing frame URL; `context.topFrameSrc`
+  is the outer document URL
+- **`onError(error)`** — called on rendering errors
+### `renderToString`
+Renders a component tree to a complete HTML string. Use for static pages or embedding HTML:
+```tsx
+import { renderToString } from 'remix/ui/server'
+let html = await renderToString(<App />)
+```
+### CSS in SSR
+Components using the `css` mixin have styles collected during rendering and emitted as a single
+`<style>` tag in `<head>`. No client-side style injection needed.
+## Navigation
+Use real anchors for normal document navigation. For app-driven navigation:
+- `navigate(href, options?)` — performs a Navigation API transition
+- `link(href, options?)` mixin — makes any element behave like a navigation link
+```tsx
+import { navigate } from 'remix/ui'
+navigate('/dashboard', { history: 'replace' })
+```
+Options: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
+Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-document`.
+## Head Management
+Manage document head with an explicit `<head>` in your document structure:
+```tsx
+function App() {
+  return () => (
+    <html>
+      <head>
+        <title>Dashboard</title>
+        <meta name="description" content="Team dashboard" />
+        <link rel="stylesheet" href="/styles/app.css" />
+      </head>
+      <body>
+        <main>...</main>
+      </body>
+    </html>
+  )
+}
+```
+Put `title`, `meta`, `link`, and `style` tags inside an explicit `<head>`. Bare head-like tags
+rendered outside `<head>` stay where they are — they are not moved into the document head for you.

package/bootstrap/.agents/skills/remix/references/middleware-and-server.md ADDED Viewed

@@ -0,0 +1,243 @@
+# Middleware and Server Setup
+## What This Covers
+How to compose the request lifecycle and bridge the router to a runtime. Read this when the task
+involves:
+- Choosing or ordering built-in middleware in the root stack
+- Writing custom middleware that sets typed context values
+- Adding fast-exit handling (static files, CORS preflights) versus request-enriching layers
+  (sessions, auth, data loading)
+- Booting a Node `http` server with `createRequestListener`
+For data and persistence specifics, see `data-and-validation.md`. For session and auth specifics,
+see `auth-and-sessions.md`.
+## Middleware Stack
+Middleware runs in order for every request. Place fast-exit middleware (static files) early and
+request-enriching middleware (session, auth) later.
+Recommended ordering:
+```typescript
+import { createRouter } from 'remix/fetch-router'
+import { compression } from 'remix/compression-middleware'
+import { formData } from 'remix/form-data-middleware'
+import { logger } from 'remix/logger-middleware'
+import { methodOverride } from 'remix/method-override-middleware'
+import { session } from 'remix/session-middleware'
+import { staticFiles } from 'remix/static-middleware'
+import { asyncContext } from 'remix/async-context-middleware'
+let middleware = []
+if (process.env.NODE_ENV === 'development') {
+  middleware.push(logger())
+}
+middleware.push(compression())
+middleware.push(staticFiles('./public'))
+middleware.push(formData())
+middleware.push(methodOverride())
+middleware.push(session(cookie, storage))
+middleware.push(asyncContext())
+middleware.push(loadDatabase())
+middleware.push(loadAuth())
+let router = createRouter({ middleware })
+```
+### Built-in middleware catalog
+| Middleware                 | Import                             | Use when                                                                      | Notes                                                          |
+| -------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `staticFiles(dir, opts?)`  | `remix/static-middleware`          | Serve files from `public/` or another directory exactly as they exist on disk | Fast exit; usually near the top                                |
+| `compression()`            | `remix/compression-middleware`     | Compress text-like responses                                                  | Usually global                                                 |
+| `logger()`                 | `remix/logger-middleware`          | Log requests and responses                                                    | Often development-only; `colors` can force color output on/off |
+| `cors(opts?)`              | `remix/cors-middleware`            | Endpoints must serve cross-origin browsers or preflight `OPTIONS` requests    | Usually early so preflights can short-circuit                  |
+| `cop(opts?)`               | `remix/cop-middleware`             | Reject unsafe cross-origin browser requests without synchronizer tokens       | Put before session or CSRF when used                           |
+| `formData(opts?)`          | `remix/form-data-middleware`       | Parse `FormData` bodies, especially forms and uploads                         | Needed for `_csrf` form field extraction                       |
+| `methodOverride()`         | `remix/method-override-middleware` | HTML forms need `PUT`, `PATCH`, or `DELETE` semantics                         | Run after form parsing                                         |
+| `session(cookie, storage)` | `remix/session-middleware`         | Cookie-backed sessions                                                        | Must run before session-backed auth or CSRF                    |
+| `csrf(opts?)`              | `remix/csrf-middleware`            | Session-backed form workflows need synchronizer-token CSRF protection         | Requires `session()` before it                                 |
+| `asyncContext()`           | `remix/async-context-middleware`   | Helpers outside handlers need request context via `getContext()`              | Add before helpers rely on it                                  |
+| `auth({ schemes })`        | `remix/auth-middleware`            | Resolve auth state into `context.get(Auth)`                                   | Run after `session()` for session-backed auth                  |
+| `requireAuth()`            | `remix/auth-middleware`            | A controller or action must reject anonymous access                           | Usually controller-level or action-level, not global           |
+### 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 `remix/assets` when browser modules should be compiled and served from source files with
+  import rewriting, preloads, or fingerprinted URLs
+### Ordering notes
+- Put fast exits early: `staticFiles()`, `cors()` preflight handling, and `cop()` when used
+- Parse request bodies before middleware that depends on them, such as `methodOverride()` and form
+  field token extraction in `csrf()`
+- Run `session()` before `csrf()` and before session-backed `auth()`
+- Add `asyncContext()` before helpers or shared code call `getContext()`
+- Keep route protection like `requireAuth()` at controller or action scope unless the entire app is
+  private
+### Common stacks
+- **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
+### Middleware with options
+```typescript
+// Static files with cache headers
+staticFiles('./public', {
+  cacheControl: 'no-store, must-revalidate',
+  etag: false,
+  lastModified: false,
+})
+// Form data with upload handler
+import { FileUpload } from 'remix/form-data-parser'
+import { createFsFileStorage } from 'remix/file-storage/fs'
+let fileStorage = createFsFileStorage('./tmp/uploads')
+formData({
+  uploadHandler(fileUpload: FileUpload) {
+    return fileStorage.set(fileUpload.name, fileUpload)
+  },
+})
+```
+Errors thrown or rejected by `uploadHandler` propagate directly. Catch domain-specific upload
+errors at the route boundary when they should become user-facing `Response` objects.
+## Writing Custom Middleware
+Middleware is a function that receives `(context, next)` and returns a `Response`. Call `next()` to
+continue the chain.
+### Setting context values
+Use `context.set(key, value)` to add typed values accessible downstream via `context.get(key)`.
+```typescript
+import type { Middleware } from 'remix/fetch-router'
+import { Database } from 'remix/data-table'
+export function loadDatabase(): Middleware {
+  return async (context, next) => {
+    context.set(Database, db)
+    return next()
+  }
+}
+```
+### Guarding routes
+```typescript
+import { Auth } from 'remix/auth-middleware'
+export function requireAdmin(): Middleware {
+  return (context, next) => {
+    let auth = context.get(Auth)
+    if (auth.identity?.role !== 'admin') {
+      return new Response('Forbidden', { status: 403 })
+    }
+    return next()
+  }
+}
+```
+### Async context for helpers
+`asyncContext()` stores the request context in `AsyncLocalStorage` so helpers can reach it
+without the context being threaded through every call. Wrap `getContext()` in app-specific
+helpers:
+```typescript
+// app/utils/context.ts
+import { getContext } from 'remix/async-context-middleware'
+import { Auth } from 'remix/auth-middleware'
+import { Database } from 'remix/data-table'
+import { Session } from 'remix/session'
+export function getCurrentDb() {
+  return getContext().get(Database)
+}
+export function getCurrentSession() {
+  return getContext().get(Session)
+}
+export function getCurrentUser() {
+  let auth = getContext().get(Auth)
+  if (!auth.ok) {
+    throw new Error('Expected an authenticated user. Run requireAuth() before this code.')
+  }
+  return auth.identity
+}
+export function getCurrentUserSafely() {
+  let auth = getContext().get(Auth)
+  return auth.ok ? auth.identity : null
+}
+```
+## Middleware Layers
+Middleware can be applied at three levels:
+1. **Router-level** — runs for every request:
+   ```typescript
+   let router = createRouter({ middleware: [...] })
+   ```
+2. **Controller-level** — runs for all actions in a controller subtree:
+   ```typescript
+   export default {
+     middleware: [requireAuth()],
+     actions: { ... },
+   } satisfies Controller<typeof routes.account>
+   ```
+3. **Action-level** — runs for a single route:
+   ```typescript
+   router.get(routes.account, {
+     middleware: [requireAuth()],
+     handler: accountAction.handler,
+   })
+   ```
+## Node Server Setup
+Use `createRequestListener` to bridge Node's `http` module to the Fetch API router:
+```typescript
+import * as http from 'node:http'
+import { createRequestListener } from 'remix/node-fetch-server'
+let server = http.createServer(
+  createRequestListener(async (request) => {
+    try {
+      return await router.fetch(request)
+    } catch (error) {
+      console.error(error)
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }),
+)
+let port = Number(process.env.PORT) || 3000
+server.listen(port, () => {
+  console.log(`http://localhost:${port}`)
+})
+```