@remix-run/cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,233 @@
+# 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)
+- 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`.
+
+## 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/router'
+import { compression } from 'remix/middleware/compression'
+import { formData } from 'remix/middleware/form-data'
+import { logger } from 'remix/middleware/logger'
+import { methodOverride } from 'remix/middleware/method-override'
+import { session } from 'remix/middleware/session'
+import { staticFiles } from 'remix/middleware/static'
+import { asyncContext } from 'remix/middleware/async-context'
+
+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/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                                                 |
+| `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                           |
+| `formData(opts?)`          | `remix/middleware/form-data`       | Parse `FormData` bodies, especially forms and uploads                         | Needed for `_csrf` form field extraction                       |
+| `methodOverride()`         | `remix/middleware/method-override` | HTML forms need `PUT`, `PATCH`, or `DELETE` semantics                         | Run after form parsing                                         |
+| `session(cookie, storage)` | `remix/middleware/session`         | Cookie-backed sessions                                                        | Must run before session-backed auth or CSRF                    |
+| `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           |
+
+### 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 type { 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)`. 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
+
+Use `context.set(key, value)` to add typed values accessible downstream via `context.get(key)`.
+
+```typescript
+import type { Middleware } from 'remix/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/middleware/auth'
+
+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/middleware/async-context'
+import { Auth } from 'remix/middleware/auth'
+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 the direct actions in one controller:
+
+   ```typescript
+   export default createController(routes.account, {
+     middleware: [requireAuth()],
+     actions: { ... },
+   })
+   ```
+
+   Controller middleware does not flow into other controllers. Add the middleware to each
+   controller that needs it.
+
+3. **Action-level** — runs for a single route:
+   ```typescript
+   router.get(routes.account.index, {
+     middleware: [requireAuth()],
+     handler: accountAction.handler,
+   })
+   ```
+
+## 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.
+
+Use `remix/node-fetch-server` when you want to keep owning a standard Node `http`, `https`, or
+`http2` server directly. Use `remix/node-serve` and `serve()` when you want a managed
+high-performance server with `server.ready`, TLS options, or uWebSockets.js setup.

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

@@ -0,0 +1,213 @@
+# Mixins, Styling, and Events
+
+## What This Covers
+
+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`
+- Imperative DOM access via `ref(...)`
+- Navigation behavior on non-anchor elements with `link(...)`
+- 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`.
+
+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:
+
+```tsx
+<input
+  mix={on('input', async (event, signal) => {
+    let query = event.currentTarget.value
+    loading = true
+    handle.update()
+
+    let response = await fetch(`/search?q=${query}`, { signal })
+    let data = await response.json()
+    if (signal.aborted) return
+
+    results = data.results
+    loading = false
+    handle.update()
+  })}
+/>
+```
+
+Multiple events on the same element:
+
+```tsx
+<form
+  mix={on('submit', (event) => {
+      event.preventDefault()
+      let formData = new FormData(event.currentTarget)
+    })}
+>
+```
+
+## `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:
+
+```tsx
+<button
+  mix={css({
+    color: 'white',
+    backgroundColor: 'blue',
+    padding: '12px 24px',
+    borderRadius: '4px',
+    border: 'none',
+    cursor: 'pointer',
+    '&:hover': { backgroundColor: 'darkblue' },
+    '&:active': { transform: 'scale(0.98)' },
+    '&:disabled': { opacity: 0.5, cursor: 'not-allowed' },
+    '& .title': { fontSize: '20px', fontWeight: 'bold' },
+    '@media (max-width: 768px)': { width: '100%' },
+  })}
+/>
+```
+
+### `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:
+
+```tsx
+<div
+  mix={css({
+    backgroundColor: 'blue', // static
+    '&:hover': { '& .title': { color: 'blue' } }, // parent hover → child
+  })}
+  style={{ width: `${progress}%` }} // dynamic
+/>
+```
+
+## `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:
+
+```tsx
+<input mix={ref((node) => node.focus())} />
+
+<div mix={ref((node, signal) => {
+  let observer = new ResizeObserver((entries) => {
+    dimensions.width = Math.round(entries[0].contentRect.width)
+    handle.update()
+  })
+  observer.observe(node)
+  signal.addEventListener('abort', () => observer.disconnect())
+})} />
+```
+
+The `ref` callback runs once when the element is first rendered, not on every update.
+
+## `link(href, options?)`
+
+Adds client-side navigation behavior to any element. Makes non-anchor elements behave like Remix
+navigation links:
+
+```tsx
+<article mix={link('/courses/intro')}>
+  <h3>Introduction</h3>
+</article>
+```
+
+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:
+
+```tsx
+<button mix={on('click', () => doAction())}>Action</button>
+```
+
+For gesture-specific behavior, compose the pointer or keyboard events the interaction actually
+needs:
+
+```tsx
+<button
+  mix={[
+    on('pointerdown', (event) => {
+      event.currentTarget.setPointerCapture(event.pointerId)
+    }),
+    on('pointerup', () => doAction()),
+  ]}
+>
+  Action
+</button>
+
+<div
+  tabIndex={0}
+  mix={on('keydown', (event) => {
+      if (event.key === 'Escape') close()
+      if (event.key === 'Enter' || event.key === ' ') doAction()
+    })}
+/>
+```
+
+## `attrs()`
+
+Sets HTML attributes through the mixin system.
+
+## Animation Mixins
+
+### `animateEntrance(config)`
+
+Animates an element when it is inserted into the DOM. Config specifies the **starting** style:
+
+```tsx
+<div mix={animateEntrance({ opacity: 0, transform: 'translateY(8px)', duration: 180 })} />
+```
+
+### `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:
+
+```tsx
+{
+  isVisible && (
+    <div
+      key="panel"
+      mix={[
+        animateEntrance({ opacity: 0, transform: 'scale(0.98)', ...spring('smooth') }),
+        animateExit({ opacity: 0, duration: 120, easing: 'ease-in' }),
+      ]}
+    />
+  )
+}
+```
+
+### `animateLayout(config?)`
+
+Animates layout changes (position/size) using FLIP-style transforms:
+
+```tsx
+{
+  items.map((item) => (
+    <li key={item.id} mix={animateLayout({ duration: 220, easing: 'ease-out' })} />
+  ))
+}
+```
+
+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.