docs: standardize package README structure and install guidance (#11056)

mjackson · web-flow · commit ef934f523767 · 2026-02-11T15:37:32.000-08:00
diff --git a/packages/async-context-middleware/README.md b/packages/async-context-middleware/README.md
@@ -1,13 +1,17 @@
 # async-context-middleware
 
-Middleware for storing request context in `AsyncLocalStorage` for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+Request-scoped async context middleware for Remix. It stores each request context in [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) so utilities can access it anywhere in the same async call stack.
 
-This middleware stores the request context in [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) (using `node:async_hooks`), making it available to all functions in the same async execution context.
+## Features
+
+- **Request Context Access** - Read request context from anywhere in the same async execution flow
+- **Simple Router Integration** - Add a single middleware at the router level
+- **Node Async Hooks** - Built on `node:async_hooks` `AsyncLocalStorage`
 
 ## Installation
 
 ```sh
-npm install @remix-run/async-context-middleware
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/component/README.md b/packages/component/README.md
@@ -1,6 +1,6 @@
-# Remix Component
+# component
 
-A minimal component system that leans on JavaScript and DOM primitives.
+A minimal component system for the web that leans on JavaScript and DOM primitives.
 
 ## Features
 
@@ -13,7 +13,7 @@ A minimal component system that leans on JavaScript and DOM primitives.
 ## Installation
 
 ```sh
-npm install @remix-run/component
+npm i remix
 ```
 
 ## Getting Started
diff --git a/packages/compression-middleware/README.md b/packages/compression-middleware/README.md
@@ -1,13 +1,18 @@
 # compression-middleware
 
-Middleware for compressing HTTP responses for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+Response compression middleware for Remix. It negotiates `br`, `gzip`, and `deflate` from `Accept-Encoding` and applies sensible defaults for when compression is useful.
 
-Automatically compresses responses using `gzip`, `brotli`, or `deflate` based on the client's `Accept-Encoding` header, with intelligent defaults for media type filtering and threshold-based compression.
+## 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 install @remix-run/compression-middleware
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/cookie/README.md b/packages/cookie/README.md
@@ -1,8 +1,6 @@
 # cookie
 
-Simplify HTTP cookie management in JavaScript with type-safe, secure cookie handling. `@remix-run/cookie` provides a clean, intuitive API for creating, parsing, and serializing HTTP cookies with built-in support for signing, secret rotation, and comprehensive cookie attribute management.
-
-HTTP cookies are essential for web applications, from session management and user preferences to authentication tokens and tracking. While the standard cookie parsing libraries provide basic functionality, they often leave complex scenarios like secure signing, secret rotation, and type-safe value handling up to you.
+Type-safe cookie parsing and serialization for Remix. It supports secure signing, secret rotation, and complete cookie attribute control.
 
 ## Features
 
@@ -13,7 +11,7 @@ HTTP cookies are essential for web applications, from session management and use
 ## Installation
 
 ```sh
-npm install @remix-run/cookie
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/fetch-proxy/README.md b/packages/fetch-proxy/README.md
@@ -1,12 +1,7 @@
 # fetch-proxy
 
-`fetch-proxy` is an HTTP proxy for the [JavaScript Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
-
-HTTP proxies are essential for many web architectures: load balancing, API gateways, development servers that forward to backend services, and middleware that needs to intercept and modify traffic. Traditional proxy implementations often require platform-specific APIs or complex server setups.
-
-In the context of servers, an HTTP proxy server is a server that forwards all requests it receives to another server and returns the responses it receives. When you think about it this way, a [`fetch` function](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) is like a mini proxy server sitting right there in your code. You send it requests, it goes and talks to some other server, and it gives you back the response it received.
-
-`fetch-proxy` allows you to easily create `fetch` functions that act as proxies to "target" servers using the familiar web-standard Fetch API.
+HTTP proxy utilities built on the web [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+Use `fetch-proxy` to create `fetch` handlers that forward requests to target servers while optionally rewriting headers and cookies.
 
 ## Features
 
@@ -17,10 +12,8 @@ In the context of servers, an HTTP proxy server is a server that forwards all re
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm i @remix-run/fetch-proxy
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/fetch-router/README.md b/packages/fetch-router/README.md
@@ -1,6 +1,6 @@
 # fetch-router
 
-A minimal, composable router built on the [web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [`route-pattern`](../route-pattern). Ideal for building APIs, web services, and server-rendered applications across any JavaScript runtime.
+A minimal, composable router built on the [web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern). Ideal for building APIs, web services, and server-rendered applications.
 
 ## Features
 
@@ -11,16 +11,10 @@ A minimal, composable router built on the [web Fetch API](https://developer.mozi
 - **Flexible Middleware**: Apply middleware globally, per-route, or to entire route hierarchies
 - **Easy Testing**: Use standard `fetch()` to test your routes - no special test harness required
 
-## Goals
-
-- **Simplicity**: A router should be simple to understand and use. The entire API surface fits in your head.
-- **Composability**: Small routers combine to build large applications. Middleware and nested routers make organization natural.
-- **Standards-Based**: Built on web standards that work across runtimes. No proprietary APIs or Node.js-specific code.
-
 ## Installation
 
 ```sh
-npm install @remix-run/fetch-router
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/file-storage/README.md b/packages/file-storage/README.md
@@ -1,10 +1,6 @@
 # file-storage
 
-`file-storage` is a key/value interface for storing [`File` objects](https://developer.mozilla.org/en-US/docs/Web/API/File) in JavaScript.
-
-Handling file uploads and storage is a common requirement in web applications, but each storage backend (local disk, AWS S3, Cloudflare R2, etc.) has its own API and conventions. This fragmentation makes it difficult to write portable code that can easily switch between storage providers or support multiple backends simultaneously.
-
-Similar to how `localStorage` allows you to store key/value pairs of strings in the browser, `file-storage` allows you to store key/value pairs of files on the server with a consistent interface regardless of the underlying storage mechanism.
+Key/value storage interfaces for server-side [`File` objects](https://developer.mozilla.org/en-US/docs/Web/API/File). `file-storage` gives Remix apps one consistent API across local disk and cloud object storage backends.
 
 ## Features
 
@@ -15,10 +11,8 @@ Similar to how `localStorage` allows you to store key/value pairs of strings in
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/file-storage
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/form-data-middleware/README.md b/packages/form-data-middleware/README.md
@@ -1,11 +1,18 @@
 # form-data-middleware
 
-Middleware for parsing [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) from incoming request bodies for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+Form body parsing middleware for Remix. It parses incoming [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and exposes `context.formData` and uploaded files on `context.files`.
+
+## Features
+
+- **Request Form Parsing** - Parses request body form data once per request
+- **File Access** - Exposes uploaded files as `context.files`
+- **Custom Upload Handling** - Supports pluggable upload handlers for file processing
+- **Error Control** - Optional suppression for malformed form data
 
 ## Installation
 
 ```sh
-npm install @remix-run/form-data-middleware
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/form-data-parser/README.md b/packages/form-data-parser/README.md
@@ -26,10 +26,8 @@ For attackers, this creates an attack vector where malicious actors can overwhel
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/form-data-parser
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/fs/README.md b/packages/fs/README.md
@@ -1,8 +1,6 @@
 # fs
 
-Lazy, streaming filesystem utilities for JavaScript.
-
-This package provides utilities for working with files on the local filesystem using the [`LazyFile`](https://github.com/remix-run/remix/tree/main/packages/lazy-file)/ native [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) API.
+Lazy, streaming filesystem utilities for JavaScript. This package provides utilities for working with files on the local filesystem using the [`LazyFile`](https://github.com/remix-run/remix/tree/main/packages/lazy-file)/ native [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) API.
 
 ## Features
 
@@ -11,10 +9,8 @@ This package provides utilities for working with files on the local filesystem u
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/fs
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/headers/README.md b/packages/headers/README.md
@@ -1,13 +1,17 @@
 # headers
 
-Utilities for parsing, manipulating and stringifying HTTP header values.
+Typed utilities for parsing, manipulating, and serializing HTTP header values. `headers` provides focused classes for common HTTP headers.
 
-HTTP headers contain critical information—from content negotiation and caching directives to authentication tokens and file metadata. While the native `Headers` API provides a basic string-based interface, it leaves the complexities of parsing specific header formats entirely up to you.
+## Features
+
+- **Header-Specific Classes** - Purpose-built APIs for `Accept`, `Cache-Control`, `Content-Type`, and more
+- **Round-Trip Safety** - Parse from raw values and serialize back with `.toString()`
+- **Typed Operations** - Work with structured values instead of manual string parsing
 
 ## Installation
 
 ```sh
-npm install @remix-run/headers
+npm i remix
 ```
 
 ## Individual Header Utilities
diff --git a/packages/html-template/README.md b/packages/html-template/README.md
@@ -1,10 +1,6 @@
 # html-template
 
-Safe HTML template tag with auto-escaping for JavaScript.
-
-Building HTML strings with user input is dangerous. Without proper escaping, you risk XSS (cross-site scripting) vulnerabilities where malicious code can be injected into your pages. Manual escaping is error-prone and easy to forget, especially when composing HTML from multiple sources.
-
-`html-template` provides a tagged template literal for safely constructing HTML strings with automatic escaping of interpolated values to prevent XSS vulnerabilities.
+Safe HTML template literals for Remix. `html-template` automatically escapes interpolated values to prevent XSS while still supporting explicit trusted HTML insertion.
 
 ## Features
 
@@ -17,10 +13,8 @@ Building HTML strings with user input is dangerous. Without proper escaping, you
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/html-template
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
@@ -12,7 +12,7 @@ Enhanced events and custom interactions for any [EventTarget](https://developer.
 ## Installation
 
 ```sh
-npm install @remix-run/interaction
+npm i remix
 ```
 
 ## Getting Started
diff --git a/packages/lazy-file/README.md b/packages/lazy-file/README.md
@@ -1,6 +1,6 @@
 # lazy-file
 
-`lazy-file` is a lazy, streaming `Blob`/`File` implementation for JavaScript.
+A lazy, streaming `Blob`/`File` implementation for JavaScript.
 
 It allows you to easily create [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)-like and [File](https://developer.mozilla.org/en-US/docs/Web/API/File)-like objects that defer reading their contents until needed, which is ideal for situations where a file's contents do not fit in memory all at once. When file contents are read, they are streamed to avoid buffering.
 
@@ -12,7 +12,7 @@ It allows you to easily create [Blob](https://developer.mozilla.org/en-US/docs/W
 - **Standard Constructors** - Accepts all the same content types as the original [`Blob()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/Blob) and [`File()`](https://developer.mozilla.org/en-US/docs/Web/API/File/File) constructors
 - **Slice Support** - Supports [`Blob.slice()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice), even on streaming content
 
-## The Problem
+## Why You Need This
 
 JavaScript's [File API](https://developer.mozilla.org/en-US/docs/Web/API/File) is useful, but it's not a great fit for streaming server environments where you don't want to buffer file contents. In particular, [`the File() constructor`](https://developer.mozilla.org/en-US/docs/Web/API/File/File) requires the contents of a file to be supplied up front when the object is first created, like this:
 
@@ -33,10 +33,8 @@ All other `File` functionality works as you'd expect.
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/lazy-file
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/logger-middleware/README.md b/packages/logger-middleware/README.md
@@ -1,13 +1,17 @@
 # logger-middleware
 
-Middleware for logging HTTP requests and responses for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+HTTP request/response logging middleware for Remix. It logs request metadata and response details with configurable output formats.
 
-Logs information about HTTP requests and responses with customizable formatting.
+## Features
+
+- **Request/Response Logging** - Logs method, path, status, and response metadata
+- **Token-Based Formatting** - Customize log output with built-in placeholders
+- **Structured Timing Data** - Includes request duration and timestamps
 
 ## Installation
 
 ```sh
-npm install @remix-run/logger-middleware
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/method-override-middleware/README.md b/packages/method-override-middleware/README.md
@@ -1,13 +1,17 @@
 # method-override-middleware
 
-Middleware for overriding HTTP request methods from form data for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+Method override middleware for Remix. It allows HTML forms to simulate `PUT`, `PATCH`, and `DELETE` requests using a hidden form field.
 
-Allows HTML forms (which only support GET and POST) to submit with other HTTP methods like PUT, PATCH, or DELETE by including a special form field.
+## Features
+
+- **Form Method Overrides** - Translate posted form fields into request methods
+- **HTML Form Friendly** - Supports REST-style routes from standard browser forms
+- **Configurable Field Name** - Choose a custom override field key
 
 ## Installation
 
 ```sh
-npm install @remix-run/method-override-middleware
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/mime/README.md b/packages/mime/README.md
@@ -1,13 +1,18 @@
-# @remix-run/mime
+# mime
 
-Utilities for working with MIME types.
+MIME type detection and content-type helpers for Remix. This package maps extensions to MIME types and provides utilities for charset and compressibility checks.
 
-Data used for these utilities is generated at build time from [mime-db](https://github.com/jshttp/mime-db).
+## Features
+
+- **MIME Detection** - Detect MIME types from extensions and filenames
+- **Content-Type Helpers** - Build `Content-Type` values with charset handling
+- **Compression Signals** - Check whether a media type is likely compressible
+- **Generated Data** - Built from [mime-db](https://github.com/jshttp/mime-db)
 
 ## Installation
 
-```bash
-npm install @remix-run/mime
+```sh
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/multipart-parser/README.md b/packages/multipart-parser/README.md
@@ -1,16 +1,6 @@
 # multipart-parser
 
-`multipart-parser` is a fast, streaming multipart parser that works in **any JavaScript environment**, from serverless functions to traditional servers. Whether you're handling file uploads, parsing email attachments, or working with multipart API responses, `multipart-parser` has you covered.
-
-## Why multipart-parser?
-
-- **Universal JavaScript** - One library that works everywhere: Node.js, Bun, Deno, Cloudflare Workers, and browsers
-- **Blazing Fast** - Consistently outperforms popular alternatives like busboy in benchmarks
-- **Zero Dependencies** - Lightweight and secure with no external dependencies
-- **Memory Efficient** - Streaming architecture that `yield`s files as they are found in the stream
-- **Type Safe** - Written in TypeScript with comprehensive type definitions
-- **Standards Based** - Built on the web standard [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) for maximum compatibility
-- **Production Ready** - Battle-tested error handling with specific error types for common scenarios
+Fast streaming multipart parsing for JavaScript. `multipart-parser` processes multipart bodies incrementally so large uploads can be handled without buffering the entire multipart payload in memory.
 
 ## Features
 
@@ -23,10 +13,8 @@
 
 ## Installation
 
-Install from [npm](https://www.npmjs.com/):
-
 ```sh
-npm install @remix-run/multipart-parser
+npm i remix
 ```
 
 ## Usage
diff --git a/packages/node-fetch-server/README.md b/packages/node-fetch-server/README.md
diff --git a/packages/remix/README.md b/packages/remix/README.md
diff --git a/packages/response/README.md b/packages/response/README.md
diff --git a/packages/route-pattern/README.md b/packages/route-pattern/README.md
diff --git a/packages/session-middleware/README.md b/packages/session-middleware/README.md
diff --git a/packages/session/README.md b/packages/session/README.md
diff --git a/packages/static-middleware/README.md b/packages/static-middleware/README.md
diff --git a/packages/tar-parser/README.md b/packages/tar-parser/README.md
