@remix-run/compression-middleware 0.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,171 @@
+# 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).
+
+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.
+
+## Installation
+
+```sh
+npm install @remix-run/compression-middleware
+```
+
+## Usage
+
+```ts
+import { createRouter } from '@remix-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+
+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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+
+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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+
+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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+
+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-run/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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+import { isCompressibleMimeType } from '@remix-run/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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+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-run/fetch-router'
+import { compression } from '@remix-run/compression-middleware'
+
+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-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`@remix-run/mime`](https://github.com/remix-run/remix/tree/main/packages/mime) - MIME type utilities
+- [`@remix-run/response`](https://github.com/remix-run/remix/tree/main/packages/response) - Response helpers
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { compression, type CompressionOptions } from './lib/compression.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { compression } from "./lib/compression.js";

package/dist/lib/compression.d.ts

@@ -0,0 +1,53 @@
+import type { BrotliOptions, ZlibOptions } from 'node:zlib';
+import type { Middleware } from '@remix-run/fetch-router';
+type Encoding = 'br' | 'gzip' | 'deflate';
+export interface CompressionOptions {
+    /**
+     * Minimum size in bytes to compress (only enforced if Content-Length present).
+     * Default: 1024
+     */
+    threshold?: number;
+    /**
+     * Optional filter to control which responses get compressed based on media type.
+     * If not provided, uses compressible media types from mime-db.
+     */
+    filterMediaType?: (mediaType: string) => boolean;
+    /**
+     * Which encodings the server supports for negotiation in order of preference.
+     * Can be static or a function that returns encodings based on the response.
+     *
+     * Default: ['br', 'gzip', 'deflate']
+     */
+    encodings?: Encoding[] | ((response: Response) => Encoding[]);
+    /**
+     * node:zlib options for gzip/deflate compression.
+     * Can be static or a function that returns options based on the response.
+     *
+     * See: https://nodejs.org/api/zlib.html#class-options
+     */
+    zlib?: ZlibOptions | ((response: Response) => ZlibOptions);
+    /**
+     * node:zlib options for Brotli compression.
+     * Can be static or a function that returns options based on the response.
+     *
+     * See: https://nodejs.org/api/zlib.html#class-brotlioptions
+     */
+    brotli?: BrotliOptions | ((response: Response) => BrotliOptions);
+}
+/**
+ * Creates a middleware handler that automatically compresses responses based on the
+ * client's Accept-Encoding header, along with an additional Content-Type filter
+ * by default to only apply compression to appropriate media types.
+ *
+ * @param options Optional compression settings
+ * @returns A middleware handler that automatically compresses responses based on the client's Accept-Encoding header
+ * @example
+ * ```ts
+ * let router = createRouter({
+ *   middleware: [compression()],
+ * })
+ * ```
+ */
+export declare function compression(options?: CompressionOptions): Middleware;
+export {};
+//# sourceMappingURL=compression.d.ts.map

package/dist/lib/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/lib/compression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAA;AAEzC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;IAEhD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,QAAQ,EAAE,CAAC,CAAA;IAE7D;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,WAAW,CAAC,CAAA;IAE1D;;;;;OAKG;IACH,MAAM,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,aAAa,CAAC,CAAA;CACjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,UAAU,CAwCpE"}

package/dist/lib/compression.js

@@ -0,0 +1,52 @@
+import { compressResponse } from '@remix-run/response/compress';
+import { isCompressibleMimeType } from '@remix-run/mime';
+/**
+ * Creates a middleware handler that automatically compresses responses based on the
+ * client's Accept-Encoding header, along with an additional Content-Type filter
+ * by default to only apply compression to appropriate media types.
+ *
+ * @param options Optional compression settings
+ * @returns A middleware handler that automatically compresses responses based on the client's Accept-Encoding header
+ * @example
+ * ```ts
+ * let router = createRouter({
+ *   middleware: [compression()],
+ * })
+ * ```
+ */
+export function compression(options) {
+    return async (context, next) => {
+        let response = await next();
+        let contentTypeHeader = response.headers.get('Content-Type');
+        if (!contentTypeHeader) {
+            return response;
+        }
+        let mediaType = contentTypeHeader.split(';')[0].trim();
+        if (!mediaType) {
+            return response;
+        }
+        let filterMediaType = options?.filterMediaType ?? isCompressibleMimeType;
+        if (!filterMediaType(mediaType)) {
+            return response;
+        }
+        let compressOptions = {
+            threshold: options?.threshold,
+            encodings: options?.encodings
+                ? typeof options.encodings === 'function'
+                    ? options.encodings(response)
+                    : options.encodings
+                : undefined,
+            zlib: options?.zlib
+                ? typeof options.zlib === 'function'
+                    ? options.zlib(response)
+                    : options.zlib
+                : undefined,
+            brotli: options?.brotli
+                ? typeof options.brotli === 'function'
+                    ? options.brotli(response)
+                    : options.brotli
+                : undefined,
+        };
+        return compressResponse(response, context.request, compressOptions);
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@remix-run/compression-middleware",
+  "version": "0.0.0",
+  "description": "Middleware for compressing HTTP responses",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remix-run/remix.git",
+    "directory": "packages/compression-middleware"
+  },
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/compression-middleware#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "@remix-run/fetch-router": "0.12.0",
+    "@remix-run/response": "0.1.0",
+    "@remix-run/mime": "0.1.0"
+  },
+  "peerDependencies": {
+    "@remix-run/fetch-router": "^0.12.0",
+    "@remix-run/mime": "^0.1.0",
+    "@remix-run/response": "^0.1.0"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "compression",
+    "gzip",
+    "brotli",
+    "deflate"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { compression, type CompressionOptions } from './lib/compression.ts'

package/src/lib/compression.ts

@@ -0,0 +1,100 @@
+import type { BrotliOptions, ZlibOptions } from 'node:zlib'
+import type { Middleware } from '@remix-run/fetch-router'
+import { compressResponse, type CompressResponseOptions } from '@remix-run/response/compress'
+import { isCompressibleMimeType } from '@remix-run/mime'
+
+type Encoding = 'br' | 'gzip' | 'deflate'
+
+export interface CompressionOptions {
+  /**
+   * Minimum size in bytes to compress (only enforced if Content-Length present).
+   * Default: 1024
+   */
+  threshold?: number
+
+  /**
+   * Optional filter to control which responses get compressed based on media type.
+   * If not provided, uses compressible media types from mime-db.
+   */
+  filterMediaType?: (mediaType: string) => boolean
+
+  /**
+   * Which encodings the server supports for negotiation in order of preference.
+   * Can be static or a function that returns encodings based on the response.
+   *
+   * Default: ['br', 'gzip', 'deflate']
+   */
+  encodings?: Encoding[] | ((response: Response) => Encoding[])
+
+  /**
+   * node:zlib options for gzip/deflate compression.
+   * Can be static or a function that returns options based on the response.
+   *
+   * See: https://nodejs.org/api/zlib.html#class-options
+   */
+  zlib?: ZlibOptions | ((response: Response) => ZlibOptions)
+
+  /**
+   * node:zlib options for Brotli compression.
+   * Can be static or a function that returns options based on the response.
+   *
+   * See: https://nodejs.org/api/zlib.html#class-brotlioptions
+   */
+  brotli?: BrotliOptions | ((response: Response) => BrotliOptions)
+}
+
+/**
+ * Creates a middleware handler that automatically compresses responses based on the
+ * client's Accept-Encoding header, along with an additional Content-Type filter
+ * by default to only apply compression to appropriate media types.
+ *
+ * @param options Optional compression settings
+ * @returns A middleware handler that automatically compresses responses based on the client's Accept-Encoding header
+ * @example
+ * ```ts
+ * let router = createRouter({
+ *   middleware: [compression()],
+ * })
+ * ```
+ */
+export function compression(options?: CompressionOptions): Middleware {
+  return async (context, next) => {
+    let response = await next()
+
+    let contentTypeHeader = response.headers.get('Content-Type')
+    if (!contentTypeHeader) {
+      return response
+    }
+
+    let mediaType = contentTypeHeader.split(';')[0].trim()
+    if (!mediaType) {
+      return response
+    }
+
+    let filterMediaType = options?.filterMediaType ?? isCompressibleMimeType
+    if (!filterMediaType(mediaType)) {
+      return response
+    }
+
+    let compressOptions: CompressResponseOptions = {
+      threshold: options?.threshold,
+      encodings: options?.encodings
+        ? typeof options.encodings === 'function'
+          ? options.encodings(response)
+          : options.encodings
+        : undefined,
+      zlib: options?.zlib
+        ? typeof options.zlib === 'function'
+          ? options.zlib(response)
+          : options.zlib
+        : undefined,
+      brotli: options?.brotli
+        ? typeof options.brotli === 'function'
+          ? options.brotli(response)
+          : options.brotli
+        : undefined,
+    }
+
+    return compressResponse(response, context.request, compressOptions)
+  }
+}