@remix-run/static-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,89 @@
+# static-middleware
+
+Middleware for serving static files from the filesystem for use with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router).
+
+Serves static files from a directory with support for ETags, range requests, and conditional requests.
+
+## Features
+
+- [ETag support](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) (weak and strong)
+- [Range request support](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests) (HTTP 206 Partial Content)
+- [Conditional request support](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) (If-None-Match, If-Modified-Since)
+- Path traversal protection
+- Automatic fall through to next middleware/handler if file not found
+
+## Installation
+
+```sh
+npm install @remix-run/static-middleware
+```
+
+## Usage
+
+Static middleware is useful for serving static files from a directory.
+
+```ts
+import { createRouter } from '@remix-run/fetch-router'
+import { staticFiles } from '@remix-run/static-middleware'
+
+let router = createRouter({
+  middleware: [staticFiles('./public')],
+})
+
+router.get('/', () => new Response('Home'))
+```
+
+### With Cache Control
+
+```ts
+let router = createRouter({
+  middleware: [
+    staticFiles('./public', {
+      cacheControl: 'public, max-age=31536000, immutable', // 1 year
+    }),
+  ],
+})
+```
+
+### Filter Files
+
+```ts
+let router = createRouter({
+  middleware: [
+    staticFiles('./public', {
+      filter(path) {
+        // Don't serve hidden files
+        return !path.startsWith('.')
+      },
+    }),
+  ],
+})
+```
+
+### Multiple Directories
+
+```ts
+let router = createRouter({
+  middleware: [
+    staticFiles('./public'),
+    staticFiles('./assets', {
+      cacheControl: 'public, max-age=31536000',
+    }),
+  ],
+})
+```
+
+## Security
+
+- Prevents path traversal attacks (e.g., `../../../etc/passwd`)
+- Only serves files with GET and HEAD requests
+- Respects the configured root directory boundary
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`lazy-file`](https://github.com/remix-run/remix/tree/main/packages/lazy-file) - Used internally for streaming file contents
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { staticFiles } from './lib/static.ts';
+export type { StaticFilesOptions } from './lib/static.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,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

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

package/dist/lib/static.d.ts

@@ -0,0 +1,38 @@
+import { type FileResponseOptions } from '@remix-run/fetch-router/response-helpers';
+import type { Middleware } from '@remix-run/fetch-router';
+export type StaticFilesOptions = FileResponseOptions & {
+    /**
+     * Filter function to determine which files should be served.
+     *
+     * @param path The relative path being requested
+     * @returns Whether to serve the file
+     */
+    filter?: (path: string) => boolean;
+};
+/**
+ * Creates a middleware that serves static files from the filesystem.
+ *
+ * Uses the URL pathname to resolve files, removing the leading slash to make it
+ * a relative path. The middleware always falls through to the handler if the file
+ * is not found or an error occurs.
+ *
+ * @param root The root directory to serve files from (absolute or relative to cwd)
+ * @param options (optional) configuration for file responses
+ *
+ * @example
+ * let router = createRouter({
+ *   middleware: [staticFiles('./public')],
+ * })
+ *
+ * @example
+ * // With cache control
+ * let router = createRouter({
+ *   middleware: [
+ *     staticFiles('./public', {
+ *       cacheControl: 'public, max-age=3600',
+ *     }),
+ *   ],
+ * })
+ */
+export declare function staticFiles(root: string, options?: StaticFilesOptions): Middleware;
+//# sourceMappingURL=static.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../src/lib/static.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,KAAK,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAEzD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CACnC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAsBtF"}

package/dist/lib/static.js

@@ -0,0 +1,44 @@
+import { findFile } from '@remix-run/lazy-file/fs';
+import { file } from '@remix-run/fetch-router/response-helpers';
+/**
+ * Creates a middleware that serves static files from the filesystem.
+ *
+ * Uses the URL pathname to resolve files, removing the leading slash to make it
+ * a relative path. The middleware always falls through to the handler if the file
+ * is not found or an error occurs.
+ *
+ * @param root The root directory to serve files from (absolute or relative to cwd)
+ * @param options (optional) configuration for file responses
+ *
+ * @example
+ * let router = createRouter({
+ *   middleware: [staticFiles('./public')],
+ * })
+ *
+ * @example
+ * // With cache control
+ * let router = createRouter({
+ *   middleware: [
+ *     staticFiles('./public', {
+ *       cacheControl: 'public, max-age=3600',
+ *     }),
+ *   ],
+ * })
+ */
+export function staticFiles(root, options = {}) {
+    let { filter, ...fileOptions } = options;
+    return async (context, next) => {
+        if (context.request.method !== 'GET' && context.request.method !== 'HEAD') {
+            return next();
+        }
+        let relativePath = context.url.pathname.replace(/^\/+/, '');
+        if (filter && !filter(relativePath)) {
+            return next();
+        }
+        let fileToServe = await findFile(root, relativePath);
+        if (!fileToServe) {
+            return next();
+        }
+        return file(fileToServe, context.request, fileOptions);
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@remix-run/static-middleware",
+  "version": "0.0.0",
+  "description": "Middleware for serving static files from the filesystem",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remix-run/remix.git",
+    "directory": "packages/static-middleware"
+  },
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/static-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.9.0",
+    "@remix-run/lazy-file": "3.8.0"
+  },
+  "peerDependencies": {
+    "@remix-run/fetch-router": "^0.9.0",
+    "@remix-run/lazy-file": "^3.8.0"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "static-files",
+    "file-server"
+  ],
+  "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,3 @@
+export { staticFiles } from './lib/static.ts'
+export type { StaticFilesOptions } from './lib/static.ts'
+

package/src/lib/static.ts

@@ -0,0 +1,63 @@
+import { findFile } from '@remix-run/lazy-file/fs'
+
+import { file, type FileResponseOptions } from '@remix-run/fetch-router/response-helpers'
+import type { Middleware } from '@remix-run/fetch-router'
+
+export type StaticFilesOptions = FileResponseOptions & {
+  /**
+   * Filter function to determine which files should be served.
+   *
+   * @param path The relative path being requested
+   * @returns Whether to serve the file
+   */
+  filter?: (path: string) => boolean
+}
+
+/**
+ * Creates a middleware that serves static files from the filesystem.
+ *
+ * Uses the URL pathname to resolve files, removing the leading slash to make it
+ * a relative path. The middleware always falls through to the handler if the file
+ * is not found or an error occurs.
+ *
+ * @param root The root directory to serve files from (absolute or relative to cwd)
+ * @param options (optional) configuration for file responses
+ *
+ * @example
+ * let router = createRouter({
+ *   middleware: [staticFiles('./public')],
+ * })
+ *
+ * @example
+ * // With cache control
+ * let router = createRouter({
+ *   middleware: [
+ *     staticFiles('./public', {
+ *       cacheControl: 'public, max-age=3600',
+ *     }),
+ *   ],
+ * })
+ */
+export function staticFiles(root: string, options: StaticFilesOptions = {}): Middleware {
+  let { filter, ...fileOptions } = options
+
+  return async (context, next) => {
+    if (context.request.method !== 'GET' && context.request.method !== 'HEAD') {
+      return next()
+    }
+
+    let relativePath = context.url.pathname.replace(/^\/+/, '')
+
+    if (filter && !filter(relativePath)) {
+      return next()
+    }
+
+    let fileToServe = await findFile(root, relativePath)
+
+    if (!fileToServe) {
+      return next()
+    }
+
+    return file(fileToServe, context.request, fileOptions)
+  }
+}