remix 3.0.0-beta.0 → 3.0.0-beta.2

package/src/cli/README.md

@@ -0,0 +1,78 @@
+# cli
+
+Command-line interface for creating and managing Remix projects.
+
+## Features
+
+- Create new Remix projects with `npx remix@next new` or installed `remix new`
+- Print shell completion scripts with `remix completion`
+- Check project environment and Remix app conventions with `remix doctor`
+- Create low-risk project and controller files with `remix doctor --fix`
+- Inspect the current app route tree with `remix routes`
+- Run project tests with `remix test`
+- Print the current Remix version with `remix version`
+- Use the same CLI through the `remix` package or the `remix/cli` API
+- Scaffold a starter app that matches the Remix project layout conventions
+
+## Installation
+
+Use `npx remix@next new <target-dir>` to scaffold a new Remix app. Install `remix` when you want the local `remix` command:
+
+```sh
+npm i remix
+```
+
+## Shell completion
+
+Install bash completion:
+
+```sh
+remix completion bash >> ~/.bashrc
+```
+
+Install zsh completion:
+
+```sh
+remix completion zsh >> ~/.zshrc
+```
+
+## Usage
+
+Use `npx remix@next new my-remix-app` to scaffold a new Remix app. After installing Remix, the equivalent local command is `remix new my-remix-app`.
+
+The rest of the CLI is available through the installed `remix` command:
+
+```sh
+remix new my-remix-app
+remix completion bash >> ~/.bashrc
+remix doctor
+remix doctor --fix
+remix routes
+remix routes --table
+remix routes --table --no-headers
+remix test
+remix version
+remix --no-color doctor
+```
+
+You can also run the CLI programmatically:
+
+```ts
+import { runRemix } from 'remix/cli'
+
+await runRemix(['new', 'my-remix-app'])
+await runRemix(['completion', 'bash'])
+await runRemix(['doctor'])
+await runRemix(['doctor', '--fix'])
+await runRemix(['routes'])
+await runRemix(['routes', '--table'])
+await runRemix(['routes', '--table', '--no-headers'])
+await runRemix(['test'])
+await runRemix(['version'])
+```
+
+`runRemix()` returns the CLI exit code as a promise.
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/compression-middleware/README.md

@@ -0,0 +1,176 @@
+# compression-middleware
+
+Response compression middleware for Remix. It negotiates `br`, `gzip`, and `deflate` from `Accept-Encoding` and applies sensible defaults for when compression is useful.
+
+## Features
+
+- **Encoding Negotiation** - Selects the best supported encoding from `Accept-Encoding`
+- **Compression Guards** - Skips already-compressed responses and range-enabled responses
+- **Size Thresholds** - Configurable minimum response size for compression
+- **MIME Filtering** - Compresses only content types likely to benefit
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [compression()],
+})
+```
+
+The middleware will automatically compress responses for compressible MIME types when:
+
+- The client supports compression (`Accept-Encoding` header with a supported encoding)
+- The response is large enough to benefit from compression (≥1024 bytes if `Content-Length` is present, by default)
+- The response hasn't already been compressed
+- The response doesn't advertise range support (`Accept-Ranges: bytes`)
+
+### Threshold
+
+**Default:** `1024` (only enforced if `Content-Length` is present)
+
+Set the minimum response size in bytes to compress:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      threshold: 2048, // Only compress responses ≥2KB
+    }),
+  ],
+})
+```
+
+### Encodings
+
+**Default:** `['br', 'gzip', 'deflate']`
+
+Customize which compression algorithms to support:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      encodings: ['br', 'gzip'], // Only use Brotli and Gzip
+    }),
+  ],
+})
+```
+
+The `encodings` option can also be a function that receives the response:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      encodings: (response) => {
+        // Use different encodings for server-sent events
+        let contentType = response.headers.get('Content-Type')
+        return contentType?.startsWith('text/event-stream;')
+          ? ['gzip', 'deflate']
+          : ['br', 'gzip', 'deflate']
+      },
+    }),
+  ],
+})
+```
+
+### Filter Media Type
+
+**Default:** Uses `isCompressibleMimeType()` from [`remix/mime`](https://github.com/remix-run/remix/tree/main/packages/mime)
+
+You can customize this behavior with the `filterMediaType` option:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+import { isCompressibleMimeType } from 'remix/mime'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      filterMediaType(mediaType) {
+        // Add a custom media type to the default compressible list
+        return isCompressibleMimeType(mediaType) || mediaType === 'application/vnd.example+data'
+      },
+    }),
+  ],
+})
+```
+
+### Compression Options
+
+**Default:** Uses Node.js defaults for [zlib](https://nodejs.org/api/zlib.html#class-options) and [Brotli](https://nodejs.org/api/zlib.html#class-brotlioptions), with automatic flush handling for server-sent events.
+
+You can pass options options to the underlying Node.js `zlib` and `brotli` compressors for fine-grained control:
+
+```ts
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+import { zlib } from 'node:zlib'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      zlib: {
+        level: 6,
+      },
+      brotli: {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+        },
+      },
+    }),
+  ],
+})
+```
+
+Like `encodings`, both `zlib` and `brotli` options can also be functions that receive the response:
+
+```ts
+import zlib from 'node:zlib'
+import { createRouter } from 'remix/router'
+import { compression } from 'remix/middleware/compression'
+
+let router = createRouter({
+  middleware: [
+    compression({
+      brotli: (response) => {
+        let contentType = response.headers.get('Content-Type')
+        return {
+          params: {
+            [zlib.constants.BROTLI_PARAM_QUALITY]: contentType?.startsWith('text/html;') ? 4 : 11,
+          },
+        }
+      },
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`remix/router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`remix/mime`](https://github.com/remix-run/remix/tree/main/packages/mime) - MIME type utilities
+- [`remix/response`](https://github.com/remix-run/remix/tree/main/packages/response) - Response helpers
+
+## License
+
+MIT

package/src/cookie/README.md

@@ -0,0 +1,106 @@
+# cookie
+
+Type-safe cookie parsing and serialization for Remix. It supports secure signing, secret rotation, and complete cookie attribute control.
+
+## Features
+
+- **Secure Cookie Signing:** Built-in cryptographic signing using HMAC-SHA256 to prevent cookie tampering, with support for secret rotation without breaking existing cookies.
+- **Secret Rotation Support:** Seamlessly rotate signing secrets while maintaining backward compatibility with existing cookies.
+- **Web Standards Compliant:** Built on Web Crypto API and standard cookie parsing, making it runtime-agnostic (Node.js, Bun, Deno, Cloudflare Workers).
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```tsx
+import { createCookie } from 'remix/cookie'
+
+let sessionCookie = createCookie('session', {
+  httpOnly: true,
+  secrets: ['s3cret1'],
+  secure: true,
+})
+
+cookie.name // "session"
+cookie.httpOnly // true
+cookie.secure // true
+cookie.signed // true
+
+// Get the value of the "session" cookie from the request's `Cookie` header
+let value = await sessionCookie.parse(request.headers.get('Cookie'))
+
+// Set the value of the cookie in a Response's `Set-Cookie` header
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+### Signing Cookies
+
+This library supports signing cookies, which is useful for ensuring the integrity of the cookie value and preventing tampering. Signing happens automatically when you provide a `secrets` option to the `Cookie` constructor.
+
+Secret rotation is also supported, so you can easily rotate in new secrets without breaking existing cookies.
+
+```tsx
+import { Cookie } from 'remix/cookie'
+
+// Start with a single secret
+let sessionCookie = createCookie('session', {
+  secrets: ['secret1'],
+})
+
+console.log(sessionCookie.signed) // true
+
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+All cookies sent in this scenario will be signed with the secret `secret1`. Later, when it's time to rotate secrets, add a new secret to the beginning of the array and all existing cookies will still be able to be parsed.
+
+```tsx
+let sessionCookie = createCookie('session', {
+  secrets: ['secret2', 'secret1'],
+})
+
+// This works for cookies signed with either secret
+let value = await sessionCookie.parse(request.headers.get('Cookie'))
+
+// Newly serialized cookies will be signed with the new secret
+let response = new Response('Hello, world!', {
+  headers: {
+    'Set-Cookie': await sessionCookie.serialize(value),
+  },
+})
+```
+
+### Custom Encoding
+
+By default, [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) and [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) are used to encode and decode the cookie value. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.
+
+```tsx
+let sessionCookie = createCookie('session', {
+  encode: (value) => value,
+  decode: (value) => value,
+})
+```
+
+This can be useful for viewing the value of cookies in a human-readable format in the browser's developer tools. But you should be sure that the cookie value contains only characters that are [valid in a cookie value](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#attributes).
+
+## Related Packages
+
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Type-safe HTTP header manipulation
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Build HTTP routers using the web fetch API
+- [`node-fetch-server`](https://github.com/remix-run/remix/tree/main/packages/node-fetch-server) - Build HTTP servers on Node.js using the web fetch API
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/cop-middleware/README.md

@@ -0,0 +1,117 @@
+# cop-middleware
+
+Cross-origin protection middleware for Remix. It mirrors Go's `CrossOriginProtection` by rejecting unsafe cross-origin browser requests without synchronizer tokens.
+
+## Features
+
+- **Browser Provenance Checks** - Uses `Sec-Fetch-Site` when present and falls back to `Origin`
+- **Trusted Origins** - Allow specific cross-origin callers by exact origin
+- **Explicit Escape Hatches** - Support insecure bypass patterns for endpoints like webhooks
+- **No Session State** - Does not require synchronizer tokens or server-side CSRF storage
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [cop()],
+})
+```
+
+## Behavior
+
+For unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`), `cop()` follows the same broad model as Go's `CrossOriginProtection`:
+
+- Allow `Sec-Fetch-Site: same-origin`
+- Allow `Sec-Fetch-Site: none`
+- Reject other `Sec-Fetch-Site` values unless the request matches a trusted origin or insecure bypass
+- If `Sec-Fetch-Site` is missing, compare `Origin` to the request host
+- If both `Sec-Fetch-Site` and `Origin` are missing, allow the request
+
+This middleware is intentionally tokenless. If you cannot guarantee the deployment assumptions behind that model, prefer [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware).
+
+## Caveats
+
+- `cop()` is a browser-origin guard, not a universal CSRF solution. It is designed for deployments that can rely on modern browser provenance signals and same-origin request handling.
+- If both `Sec-Fetch-Site` and `Origin` are missing on an unsafe request, `cop()` allows the request to continue. This is intentional so older clients and non-browser callers do not fail closed by default.
+- If `Sec-Fetch-Site` is missing, `cop()` only rejects when `Origin` is present and does not match the request host.
+- If you need stronger guarantees for session-backed form workflows, mixed deployment environments, or requests that should not fall through when browser provenance headers are missing, use [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware) or layer both middlewares together.
+
+## Using with csrf-middleware
+
+You can also layer `cop()` in front of `csrf()` when you want both browser provenance checks and session-backed synchronizer tokens.
+
+```ts
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/router'
+import { createCookieSessionStorage } from 'remix/session-storage/cookie'
+import { session } from 'remix/middleware/session'
+import { cop } from 'remix/middleware/cop'
+import { csrf } from 'remix/middleware/csrf'
+
+let sessionCookie = createCookie('__session', { secrets: ['secret1'] })
+let sessionStorage = createCookieSessionStorage()
+
+let router = createRouter({
+  middleware: [cop(), session(sessionCookie, sessionStorage), csrf()],
+})
+```
+
+In this setup, `cop()` runs first and rejects unsafe cross-origin browser requests early using `Sec-Fetch-Site` and `Origin`. Requests that pass `cop()` continue into `csrf()`, which still enforces synchronizer-token validation and origin checks for the remaining traffic.
+
+## Trusted Origins
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [
+    cop({
+      trustedOrigins: ['https://admin.example.com'],
+    }),
+  ],
+})
+```
+
+Trusted origins must be exact origin values in the form `scheme://host[:port]`.
+
+## Insecure Bypass Patterns
+
+Bypass patterns intentionally weaken protection for specific endpoints. They support:
+
+- Optional method prefixes, for example `POST /webhooks/{provider}`
+- Exact paths, for example `/healthz`
+- Trailing-slash subtree patterns, for example `/webhooks/`
+- Single-segment wildcards with `{name}`
+- Tail wildcards with `{name...}`
+
+```ts
+import { createRouter } from 'remix/router'
+import { cop } from 'remix/middleware/cop'
+
+let router = createRouter({
+  middleware: [
+    cop({
+      insecureBypassPatterns: ['POST /webhooks/{provider}', '/healthz'],
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`csrf-middleware`](https://github.com/remix-run/remix/tree/main/packages/csrf-middleware) - Session-backed CSRF protection with synchronizer tokens
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/cors-middleware/README.md

@@ -0,0 +1,174 @@
+# cors-middleware
+
+CORS middleware for Remix. It adds standard CORS response headers to Fetch API servers and can either short-circuit preflight requests or pass them through to app-defined `OPTIONS` handlers.
+
+## Features
+
+- **Preflight Handling** - Automatically handles `OPTIONS` preflight requests
+- **Flexible Origin Rules** - Supports static, regex, list, and function-based origin policies
+- **Credential Support** - Supports credentialed requests with spec-safe origin reflection
+- **Header Controls** - Configure allowed and exposed headers, preflight methods, and max age
+- **Private Network Support** - Optionally allow private network preflight requests
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/router'
+import { cors } from 'remix/middleware/cors'
+
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+      exposedHeaders: ['X-Request-Id'],
+    }),
+  ],
+})
+
+router.get('/api/projects', () => {
+  return Response.json([{ id: 'p1', name: 'Remix' }], {
+    headers: {
+      'X-Request-Id': 'req_123',
+    },
+  })
+})
+```
+
+## Origin Policies
+
+`origin` supports:
+
+- `'*'` to allow all origins
+- `string` for a single exact origin
+- `RegExp` for pattern-based matching
+- `Array<string | RegExp>` for multiple exact and pattern matches
+- `true` to reflect the request origin
+- `(origin, context) => boolean | string` for dynamic policies
+
+### Restrict Origins
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+    }),
+  ],
+})
+```
+
+### Dynamic Origin Policies
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin(origin, context) {
+        if (context.url.pathname.startsWith('/public/')) {
+          return '*'
+        }
+
+        return origin.endsWith('.trusted.example')
+      },
+    }),
+  ],
+})
+```
+
+## Preflight Behavior
+
+By default, preflight requests are short-circuited with status `204`.
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      methods: ['GET', 'POST', 'PATCH'],
+      allowedHeaders: ['Authorization', 'Content-Type'],
+      maxAge: 600,
+    }),
+  ],
+})
+```
+
+Use a function-based `allowedHeaders` policy when the header allowlist depends on the request:
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowedHeaders(request) {
+        let requestedHeaders = request.headers.get('Access-Control-Request-Headers')
+
+        if (requestedHeaders?.includes('x-admin-token')) {
+          return ['Authorization', 'Content-Type', 'X-Admin-Token']
+        }
+
+        return ['Authorization', 'Content-Type']
+      },
+    }),
+  ],
+})
+```
+
+Function-based `allowedHeaders` responses vary on `Access-Control-Request-Headers`, so caches do not reuse a preflight response for a different requested-header set.
+
+Set `preflightContinue: true` to let downstream handlers process preflight requests. Use `preflightStatusCode` when you want short-circuited preflight responses to return a status other than `204`.
+
+## Private Network Preflights
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowPrivateNetwork: true,
+    }),
+  ],
+})
+```
+
+When `allowPrivateNetwork` is enabled, the middleware adds `Access-Control-Allow-Private-Network: true` for preflight requests that ask for private network access.
+
+## Expose Response Headers
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      exposedHeaders: ['X-Request-Id', 'X-Trace-Id'],
+    }),
+  ],
+})
+```
+
+## Caveats
+
+- CORS is primarily a browser enforcement mechanism. Disallowed non-preflight requests still reach your handlers unless you add separate request validation.
+- When `credentials: true` is used with `origin: '*'`, the middleware reflects the request origin and adds `Vary: Origin` so the response stays cache-safe.
+- When `allowedHeaders` is a function, preflight responses vary on `Access-Control-Request-Headers` so caches do not reuse a response for a different requested-header set.
+- `preflightContinue` and `preflightStatusCode` only affect how preflight `OPTIONS` requests are handled. They do not change actual request authorization.
+
+## Related Packages
+
+- [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) - Browser-origin protection middleware for unsafe cross-origin requests
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Typed HTTP header utilities
+
+## Related Work
+
+- [MDN: Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+- [Fetch Standard: CORS protocol](https://fetch.spec.whatwg.org/#http-cors-protocol)
+- [expressjs/cors](https://github.com/expressjs/cors)
+- [rack-cors](https://github.com/cyu/rack-cors)
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)