npm - @remix-run/cli - Versions diffs - 0.3.1 → 0.3.3 - Mend

@remix-run/cli 0.3.1 → 0.3.3

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 (17) hide show

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

@@ -2,8 +2,7 @@
 ## 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:
+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`
@@ -12,19 +11,13 @@ navigation. Read this when the task involves:
 - 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`.
 ## 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.
+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.
+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) => {
@@ -39,15 +32,11 @@ on('submit', async (event, signal) => {
 })
 ```
-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.
+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:
+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'
@@ -76,9 +65,7 @@ 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, 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 />, {
@@ -96,21 +83,15 @@ let stream = renderToStream(<App />, {
 })
 ```
-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 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.
+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.
+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:
+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'
@@ -137,10 +118,8 @@ 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.
+- **`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
@@ -152,8 +131,7 @@ await app.ready()
 ## 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.
+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'
@@ -177,10 +155,8 @@ function App() {
 ### 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
+- **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
@@ -197,21 +173,17 @@ await handle.frames.get('cart-summary')?.reload()
 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.
+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.
+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:
+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'
@@ -235,11 +207,8 @@ return new Response(stream, {
 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
+- **`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`
@@ -253,8 +222,7 @@ 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.
+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
@@ -293,5 +261,4 @@ function App() {
 }
 ```
-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.
+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/template/.agents/skills/remix/references/middleware-and-server.md CHANGED Viewed

@@ -2,22 +2,18 @@
 ## What This Covers
-How to compose the request lifecycle and bridge the router to a runtime. Read this when the task
-involves:
+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
+- Choosing or ordering built-in middleware in the 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)
+- 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
-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`.
 ## Middleware Stack
-Middleware runs in order for every request. Place fast-exit middleware (static files) early and
-request-enriching middleware (session, auth) later.
+Middleware runs in order for every request. Place fast-exit middleware (static files) early and request-enriching middleware (session, auth) later.
 Recommended ordering:
@@ -54,7 +50,7 @@ let router = createRouter({ middleware })
 | Middleware                 | Import                             | Use when                                                                      | Notes                                                          |
 | -------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `staticFiles(dir, opts?)`  | `remix/middleware/static`          | Serve files from `public/` or another directory exactly as they exist on disk | Fast exit; usually near the top                                |
-| `compression()`            | `remix/middleware/compression`     | Compress text-like responses                                                  | Usually global                                                 |
+| `compression()`            | `remix/middleware/compression`     | Compress text-like responses                                                  | Usually app-wide                                               |
 | `logger()`                 | `remix/middleware/logger`          | Log requests and responses                                                    | Often development-only; `colors` can force color output on/off |
 | `cors(opts?)`              | `remix/middleware/cors`            | Endpoints must serve cross-origin browsers or preflight `OPTIONS` requests    | Usually early so preflights can short-circuit                  |
 | `cop(opts?)`               | `remix/middleware/cop`             | Reject unsafe cross-origin browser requests without synchronizer tokens       | Put before session or CSRF when used                           |
@@ -64,33 +60,26 @@ let router = createRouter({ middleware })
 | `csrf(opts?)`              | `remix/middleware/csrf`            | Session-backed form workflows need synchronizer-token CSRF protection         | Requires `session()` before it                                 |
 | `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-level or action-level, not global           |
+| `requireAuth()`            | `remix/middleware/auth`            | A controller or action must reject anonymous access                           | Usually controller middleware or action 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 `remix/assets` when browser modules should be compiled and served from source files with
-  import rewriting, preloads, or fingerprinted URLs
+- 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()`
+- 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
+- Keep route protection like `requireAuth()` as controller middleware or action middleware 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
+- **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
@@ -115,14 +104,11 @@ formData({
 })
 ```
-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.
+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)`. Return a `Response` to short-circuit, call
-and return `next()` when you need the downstream response, or return nothing when you only set
-context and want the router to continue automatically.
+Middleware is a function that receives `(context, next)`. Return a `Response` to short-circuit, call and return `next()` when you need the downstream response, or return nothing when you only set context and want the router to continue automatically.
 ### Setting context values
@@ -158,9 +144,7 @@ export function requireAdmin(): Middleware {
 ### 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:
+`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
@@ -191,17 +175,17 @@ export function getCurrentUserSafely() {
 }
 ```
-## Middleware Layers
+## Middleware Types
-Middleware can be applied at three levels:
+Middleware has three API-owned forms:
-1. **Router-level** — runs for every request:
+1. **Router middleware** — runs for every request:
    ```typescript
-   let router = createRouter({ middleware: [...] })
+   let router = createRouter({ middleware: [logger(), session(cookie, storage)] })
    ```
-2. **Controller-level** — runs for the direct actions in one controller:
+2. **Controller middleware** — runs for the direct actions in one controller:
    ```typescript
    export default createController(routes.account, {
@@ -210,23 +194,23 @@ Middleware can be applied at three levels:
    })
    ```
-   Controller middleware does not flow into other controllers. Add the middleware to each
-   controller that needs it.
+   Controller middleware does not flow into other controllers. Add the middleware to each controller that needs it.
+3. **Action middleware** — runs for a single action:
-3. **Action-level** — runs for a single route:
    ```typescript
    router.get(routes.account.index, {
      middleware: [requireAuth()],
-     handler: accountAction.handler,
+     handler(context) {
+       return render(<AccountPage identity={context.auth.identity} />)
+     },
    })
    ```
+Prefer inline arrays for `middleware` options. Use `RouterContext<typeof router>` to derive an app context from a router that uses inline middleware. Use `createMiddleware()` only when a chain is stored in a variable and its exact tuple type needs to be preserved, such as when deriving `MiddlewareContext<typeof rootMiddleware>` without a router value, exporting a reusable chain, or returning a chain from a factory.
 ## Node Server Setup
-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.
+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.
+Use `remix/node-fetch-server` when you want to keep owning a standard Node `http`, `https`, or `http2` server directly.

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

@@ -2,8 +2,7 @@
 ## What This Covers
-How to attach behavior, styles, and DOM-aware setup to host elements with `mix`. Read this when the
-task involves:
+How to attach behavior, styles, and DOM-aware setup to host elements with `mix`. Read this when the task involves:
 - DOM event handling with `on(...)`
 - Static styling with `css(...)` and dynamic styling with `style`
@@ -12,18 +11,13 @@ task involves:
 - Native click, pointer, and keyboard behavior with `on(...)`, plus attributes with `attrs(...)`
 - Element-level animation mixins from `remix/ui/animation`
-For richer animation work (springs, tweens, layout transitions), see `animate-elements.md`. For
-authoring custom mixins, see `create-mixins.md`. For component lifecycle and updates, see
-`component-model.md`.
+For richer animation work (springs, tweens, layout transitions), see `animate-elements.md`. For authoring custom mixins, see `create-mixins.md`. For component lifecycle and updates, see `component-model.md`.
-Compose behavior on host elements with `mix`. Pass a single mixin directly (`mix={on(...)}`), or
-an array when composing multiple mixins (`mix={[css(...), on(...)]}`). Core mixins are imported
-from `remix/ui`; animation mixins are imported from `remix/ui/animation`.
+Compose behavior on host elements with `mix`. Pass a single mixin directly (`mix={on(...)}`), or an array when composing multiple mixins (`mix={[css(...), on(...)]}`). Core mixins are imported from `remix/ui`; animation mixins are imported from `remix/ui/animation`.
 ## `on(type, handler, capture?)`
-Attaches a typed DOM event handler. The handler receives the event and an `AbortSignal` that aborts
-when the handler is re-entered or the component is removed — this prevents race conditions:
+Attaches a typed DOM event handler. The handler receives the event and an `AbortSignal` that aborts when the handler is re-entered or the component is removed — this prevents race conditions:
 ```tsx
 <input
@@ -56,9 +50,7 @@ Multiple events on the same element:
 ## `css(styles)`
-Applies generated class names for CSS object styles. Produces static CSS rules inserted into the
-document. Supports pseudo-selectors, pseudo-elements, attribute selectors, descendant selectors, and
-media queries using `&` to reference the current element:
+Applies generated class names for CSS object styles. Produces static CSS rules inserted into the document. Supports pseudo-selectors, pseudo-elements, attribute selectors, descendant selectors, and media queries using `&` to reference the current element:
 ```tsx
 <button
@@ -80,9 +72,7 @@ media queries using `&` to reference the current element:
 ### `css(...)` vs `style` prop
-Use `css(...)` for static styles, selectors, and media queries. Use `style` for dynamic values that
-change often. Prefer CSS nested selectors for parent-state-affects-children over managing hover/focus
-state in JavaScript:
+Use `css(...)` for static styles, selectors, and media queries. Use `style` for dynamic values that change often. Prefer CSS nested selectors for parent-state-affects-children over managing hover/focus state in JavaScript:
 ```tsx
 <div
@@ -96,8 +86,7 @@ state in JavaScript:
 ## `ref(callback)`
-Calls a callback when an element is inserted. The callback receives the DOM node and an
-`AbortSignal` that aborts when the element is removed:
+Calls a callback when an element is inserted. The callback receives the DOM node and an `AbortSignal` that aborts when the element is removed:
 ```tsx
 <input mix={ref((node) => node.focus())} />
@@ -116,8 +105,7 @@ The `ref` callback runs once when the element is first rendered, not on every up
 ## `link(href, options?)`
-Adds client-side navigation behavior to any element. Makes non-anchor elements behave like Remix
-navigation links:
+Adds client-side navigation behavior to any element. Makes non-anchor elements behave like Remix navigation links:
 ```tsx
 <article mix={link('/courses/intro')}>
@@ -125,20 +113,17 @@ navigation links:
 </article>
 ```
-Options match `NavigationOptions`: `src`, `target`, `history` (`'push' | 'replace'`),
-`resetScroll`.
+Options match `NavigationOptions`: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
 ## 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:
+Use native DOM events directly with `on(...)`. For buttons and links, `click` already includes keyboard activation when the element has the right semantics:
 ```tsx
 <button mix={on('click', () => doAction())}>Action</button>
 ```
-For gesture-specific behavior, compose the pointer or keyboard events the interaction actually
-needs:
+For gesture-specific behavior, compose the pointer or keyboard events the interaction actually needs:
 ```tsx
 <button
@@ -177,8 +162,7 @@ Animates an element when it is inserted into the DOM. Config specifies the **sta
 ### `animateExit(config)`
-Animates an element when it is removed. Config specifies the **ending** style. The element is kept
-in the DOM until the animation completes:
+Animates an element when it is removed. Config specifies the **ending** style. The element is kept in the DOM until the animation completes:
 ```tsx
 {
@@ -206,8 +190,6 @@ Animates layout changes (position/size) using FLIP-style transforms:
 }
 ```
-Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (boolean, default
-true — include scale projection for size changes).
+Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (boolean, default true — include scale projection for size changes).
-Always key elements you expect to animate. Use `...spring(preset)` to spread `duration` and
-`easing` into any animation config.
+Always key elements you expect to animate. Use `...spring(preset)` to spread `duration` and `easing` into any animation config.