@remix-run/cli 0.1.0 → 0.3.0

package/template/.agents/skills/remix/references/animate-elements.md

@@ -0,0 +1,195 @@
+# Animating Elements
+
+## What This Covers
+
+How to animate insertion, removal, and layout changes of elements. Read this when the task
+involves:
+
+- Adding entrance, exit, or shared-layout transitions to UI
+- Choosing between spring physics (`spring(...)`) and time-based easing (`tween`)
+- Coordinating CSS transitions with the same easing as JS animations
+- Imperative animation loops via `requestAnimationFrame`
+
+Import animation APIs from `remix/ui/animation`. For the smaller set of animation helpers that
+show up alongside other mixins, see `mixins-styling-events.md`.
+
+## Animation Mixins
+
+### `animateEntrance(config)`
+
+Animates an element when inserted. Config specifies the **starting** style the element animates
+**from**:
+
+```tsx
+<div
+  mix={animateEntrance({
+    opacity: 0,
+    transform: 'translateY(8px)',
+    ...spring('smooth'),
+  })}
+/>
+```
+
+### `animateExit(config)`
+
+Animates an element when removed. Config specifies the **ending** style the element animates
+**to**. The element stays 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({ ...spring({ duration: 500, bounce: 0.2 }) })} />
+  ))
+}
+```
+
+Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (default true —
+include scale projection for size changes).
+
+### Combining mixins
+
+```tsx
+<div
+  key="card"
+  mix={[
+    animateEntrance({ opacity: 0, transform: 'scale(0.95)', ...spring('snappy') }),
+    animateExit({ opacity: 0, transform: 'scale(0.98)', duration: 120, easing: 'ease-in' }),
+    animateLayout({ duration: 220, easing: 'ease-out' }),
+  ]}
+/>
+```
+
+### Shared-layout swap
+
+```tsx
+<div mix={css({ display: 'grid', '& > *': { gridArea: '1 / 1' } })}>
+  {stateA ? (
+    <div key="a" mix={[animateEntrance({ opacity: 0 }), animateExit({ opacity: 0 })]} />
+  ) : (
+    <div key="b" mix={[animateEntrance({ opacity: 0 }), animateExit({ opacity: 0 })]} />
+  )}
+</div>
+```
+
+## Spring API
+
+Physics-based spring animation. Returns a `SpringIterator` with `duration`, `easing`, and
+`toString()` for CSS.
+
+### Presets
+
+| Preset   | Bounce | Duration | Character                   |
+| -------- | ------ | -------- | --------------------------- |
+| `smooth` | -0.3   | 400ms    | Overdamped, no overshoot    |
+| `snappy` | 0      | 200ms    | Critically damped, quick    |
+| `bouncy` | 0.3    | 400ms    | Underdamped, visible bounce |
+
+```tsx
+spring('bouncy')
+spring('snappy')
+spring('smooth')
+spring('bouncy', { duration: 300 }) // override duration
+```
+
+### Custom spring
+
+```tsx
+spring({ duration: 500, bounce: 0.3 })
+spring({ duration: 500, bounce: 0.3, velocity: 2 }) // continue momentum from gesture
+```
+
+### Spread into animation mixins
+
+Spreading a spring gives both `duration` and `easing`:
+
+```tsx
+animateEntrance({ opacity: 0, ...spring('bouncy') })
+```
+
+### CSS transitions
+
+The iterator stringifies to `"550ms linear(...)"`:
+
+```tsx
+css({ transition: `width ${spring('bouncy')}` })
+```
+
+Or use the `spring.transition()` helper for multiple properties:
+
+```tsx
+css({ transition: spring.transition('width', 'bouncy') })
+css({ transition: spring.transition(['left', 'top'], 'snappy') })
+```
+
+### Web Animations API
+
+```tsx
+element.animate(keyframes, { ...spring('bouncy') })
+```
+
+### JS iteration
+
+The iterator yields position values from 0 to 1, one per frame:
+
+```tsx
+for (let t of spring('bouncy')) {
+  let x = from + (to - from) * t
+  updateSomething(x)
+  await nextFrame()
+}
+```
+
+## Tween API
+
+Generator-based tween for animating values over time with cubic bezier easing. Prefer animation
+mixins or CSS transitions with `spring` for most UI work. Use `tween` for imperative
+`requestAnimationFrame` loops, canvas/WebGL, or non-CSS properties.
+
+```tsx
+import { tween, easings } from 'remix/ui/animation'
+
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 300,
+  curve: easings.easeOut,
+})
+
+animation.next() // initialize
+function tick(timestamp: number) {
+  if (handle.signal.aborted) return
+  let { value, done } = animation.next(timestamp)
+  element.style.transform = `translateX(${value}px)`
+  if (!done) requestAnimationFrame(tick)
+}
+requestAnimationFrame(tick)
+```
+
+Built-in easings: `easings.linear`, `easings.ease`, `easings.easeIn`, `easings.easeOut`,
+`easings.easeInOut`.
+
+## Practical Guidance
+
+- Always key conditional or switching elements you expect to animate.
+- Use `animateLayout` only on the element whose position or size changes.
+- Prefer one clear transition intent per mixin: entrance starts from a style, exit ends at a style.
+- Default to `...spring()` for duration and easing in most cases.
+- Keep DOM work in `handle.queueTask(...)` or `ref(...)`, not in render.

package/template/.agents/skills/remix/references/assets-and-browser-modules.md

@@ -0,0 +1,130 @@
+# Assets and Browser Modules
+
+## What This Covers
+
+How to serve browser scripts and styles from source. Read this when the task involves:
+
+- Configuring `createAssetServer` (`basePath`, `fileMap`, `allow`, `deny`, fingerprinting,
+  compiler options)
+- Choosing between `staticFiles()` for already-built files and `createAssetServer()` for source
+  assets that need import rewriting, preloads, or fingerprinted URLs
+- Generating script URLs or `<link rel="modulepreload">` tags for a client entry
+- Keeping server-only files out of the browser via `deny` rules
+
+For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry
+hydration, see `hydration-frames-navigation.md`.
+
+## When To Reach For It
+
+Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files.
+This is the right tool for client entrypoints, browser-only helpers, styles under `app/assets/`,
+and monorepo code that should be compiled and served under a public URL namespace.
+
+Use `staticFiles()` for files that already exist on disk exactly as they should be served. Use
+`createAssetServer()` for source scripts or styles that need rewriting, dependency scanning,
+preloads, sourcemaps, or fingerprinted URLs.
+
+## Default Pattern
+
+```typescript
+import { createAssetServer } from 'remix/assets'
+import { createController } from 'remix/router'
+import { get, route } from 'remix/routes'
+
+export const routes = route({
+  assets: get('/assets/*path'),
+})
+
+let assetServer = createAssetServer({
+  basePath: '/assets',
+  rootDir: process.cwd(),
+  fileMap: {
+    'app/*path': 'app/*path',
+    'node_modules/*path': 'node_modules/*path',
+  },
+  allow: ['app/assets/**', 'node_modules/**'],
+  deny: ['app/**/*.server.*'],
+  target: { es: '2020', chrome: '109', safari: '16.4' },
+  sourceMaps: process.env.NODE_ENV === 'development' ? 'external' : undefined,
+  minify: process.env.NODE_ENV === 'production',
+  scripts: {
+    define: {
+      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'development'),
+    },
+  },
+})
+
+export default createController(routes, {
+  actions: {
+    async assets({ request }) {
+      return (await assetServer.fetch(request)) ?? new Response('Not Found', { status: 404 })
+    },
+  },
+})
+```
+
+## Rules
+
+- Treat `allow` and `deny` as the security boundary for browser-reachable source files.
+- Add a `deny` list for server-only modules such as `*.server.*`, private config, or other files
+  that should never be exposed.
+- Set `rootDir` explicitly in monorepos so relative paths resolve from the intended project root.
+- `basePath` is the public URL namespace handled by the asset server.
+- `fileMap` keys are URL patterns relative to `basePath`, and values are root-relative file path
+  patterns. They use `route-pattern` syntax on both sides.
+- Keep the same wildcard params on both sides of a `fileMap` entry so import rewriting can map
+  source files back to public URLs.
+- CSS files are compiled and served alongside scripts. Local CSS `@import` rules are rewritten and
+  fingerprinted with the same asset server routing rules.
+
+## Rendering HTML
+
+Use `getHref()` when you need the public URL for one module, and `getPreloads()` when you want
+`<link rel="modulepreload">` tags or `Link` headers for one or more entrypoints and their
+dependencies.
+
+```typescript
+let entryHref = await assetServer.getHref('app/assets/entry.ts')
+let preloads = await assetServer.getPreloads(['app/assets/entry.ts'])
+```
+
+Use this when rendering documents or layouts that boot browser behavior with a known client entry.
+
+When resolving hydrated client entries during server rendering, pass the source entry ID from
+`clientEntry(import.meta.url, ...)` to `getHref()` inside `resolveClientEntry`. Keep export-name
+resolution in that render helper, and avoid hard-coding public asset URLs in source-owned component
+modules.
+
+## Development vs Deployment
+
+In development:
+
+- Keep `watch` enabled so source changes are picked up without restarting the server
+- Prefer stable URLs with normal revalidation
+- Enable source maps when debugging browser code
+
+In deployment:
+
+- Set `watch: false`
+- Use `fingerprint: { buildId }` for long-lived immutable caching
+- Make sure `buildId` changes for each deploy
+
+Fingerprinting assumes files on disk are stable and requires `watch: false`.
+
+## Useful Compiler Options
+
+- `minify` for production minification of scripts and styles
+- `sourceMaps` for `'external'` or `'inline'` source maps for scripts and styles
+- `sourceMapSourcePaths` for `'url'` or `'absolute'` source map paths
+- `target` as an object for shared browser targets and script-only ECMAScript output, such as
+  `{ es: '2020', chrome: '109', safari: '16.4' }`
+- `scripts.define` to replace globals such as `process.env.NODE_ENV`
+- `scripts.external` to leave specific script imports untouched
+
+Do not nest shared compiler options under `scripts`. Use top-level `minify`, `sourceMaps`,
+`sourceMapSourcePaths`, and `target` so they apply to styles as well as scripts.
+
+## Lifecycle
+
+If the asset server is long-lived and watching the file system, call `await assetServer.close()`
+when shutting down dev servers or disposing tests.