@remix-run/form-data-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,79 @@
+# 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).
+
+## Installation
+
+```sh
+npm install @remix-run/form-data-middleware
+```
+
+## Usage
+
+Use the `formData()` middleware at the router level to parse `FormData` from the request body and make it available on the request context as `context.formData`.
+
+`context.files` will also be available as a map of `File` objects keyed by the name of the form field.
+
+```ts
+import { createRouter } from '@remix-run/fetch-router'
+import { formData } from '@remix-run/form-data-middleware'
+
+let router = createRouter({
+  middleware: [formData()],
+})
+
+router.post('/users', async (context) => {
+  let name = context.formData.get('name')
+  let email = context.formData.get('email')
+
+  // Handle file uploads
+  let avatar = context.files?.get('avatar')
+
+  return Response.json({ name, email, hasAvatar: !!avatar })
+})
+```
+
+### Custom File Upload Handler
+
+You can use a custom upload handler to customize how file uploads are handled. The return value of the upload handler will be used as the value of the form field in the `FormData` object.
+
+```ts
+import { formData } from '@remix-run/form-data-middleware'
+import { writeFile } from 'node:fs/promises'
+
+let router = createRouter({
+  middleware: [
+    formData({
+      async uploadHandler(upload) {
+        // Save to disk and return path
+        let path = `./uploads/${upload.name}`
+        await writeFile(path, Buffer.from(await upload.arrayBuffer()))
+        return path
+      },
+    }),
+  ],
+})
+```
+
+### Suppress Parse Errors
+
+Some requests may contain invalid form data that cannot be parsed. You can suppress parse errors by setting `suppressErrors` to `true`. In these cases, `context.formData` will be an empty `FormData` object.
+
+```ts
+let router = createRouter({
+  middleware: [
+    formData({
+      suppressErrors: true, // Invalid form data won't throw
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`form-data-parser`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser) - The underlying form data parser
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FormDataParseError } from '@remix-run/form-data-parser';
+export type { FileUpload, FileUploadHandler } from '@remix-run/form-data-parser';
+export { type FormDataOptions, formData } from './lib/form-data.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,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAEhF,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FormDataParseError } from '@remix-run/form-data-parser';
+export { formData } from "./lib/form-data.js";

package/dist/lib/form-data.d.ts

@@ -0,0 +1,21 @@
+import { type FileUploadHandler, type ParseFormDataOptions } from '@remix-run/form-data-parser';
+import type { Middleware } from '@remix-run/fetch-router';
+export interface FormDataOptions extends ParseFormDataOptions {
+    /**
+     * Set `true` to suppress parse errors. Default is `false`.
+     */
+    suppressErrors?: boolean;
+    /**
+     * A function that handles file uploads. It receives a `FileUpload` object and may return any
+     * value that is a valid `FormData` value. Default is `undefined`, which means file uploads are
+     * stored in memory.
+     */
+    uploadHandler?: FileUploadHandler;
+}
+/**
+ * Middleware that parses `FormData` from the request body and populates `context.formData`.
+ * @param options Options for parsing form data
+ * @returns A middleware function that parses form data
+ */
+export declare function formData(options?: FormDataOptions): Middleware;
+//# sourceMappingURL=form-data.d.ts.map

package/dist/lib/form-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/lib/form-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAA;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,yBAAyB,CAAA;AAEzE,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,UAAU,CA8B9D"}

package/dist/lib/form-data.js

@@ -0,0 +1,31 @@
+import { FormDataParseError, parseFormData, } from '@remix-run/form-data-parser';
+/**
+ * Middleware that parses `FormData` from the request body and populates `context.formData`.
+ * @param options Options for parsing form data
+ * @returns A middleware function that parses form data
+ */
+export function formData(options) {
+    let suppressErrors = options?.suppressErrors ?? false;
+    let uploadHandler = options?.uploadHandler;
+    return async (context) => {
+        // Get the method from context to respect any method override middleware
+        let method = context.method;
+        if (method === 'GET' || method === 'HEAD') {
+            return;
+        }
+        let contentType = context.headers.get('Content-Type');
+        if (contentType == null ||
+            (!contentType.startsWith('multipart/') &&
+                !contentType.startsWith('application/x-www-form-urlencoded'))) {
+            return;
+        }
+        try {
+            context.formData = await parseFormData(context.request, options, uploadHandler);
+        }
+        catch (error) {
+            if (!suppressErrors || !(error instanceof FormDataParseError)) {
+                throw error;
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@remix-run/form-data-middleware",
+  "version": "0.0.0",
+  "description": "Middleware for parsing FormData from request bodies",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remix-run/remix.git",
+    "directory": "packages/form-data-middleware"
+  },
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/form-data-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/form-data-parser": "0.14.0"
+  },
+  "peerDependencies": {
+    "@remix-run/fetch-router": "^0.9.0",
+    "@remix-run/form-data-parser": "^0.14.0"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "form-data",
+    "multipart",
+    "file-upload"
+  ],
+  "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,5 @@
+export { FormDataParseError } from '@remix-run/form-data-parser'
+export type { FileUpload, FileUploadHandler } from '@remix-run/form-data-parser'
+
+export { type FormDataOptions, formData } from './lib/form-data.ts'
+

package/src/lib/form-data.ts

@@ -0,0 +1,58 @@
+import {
+  FormDataParseError,
+  parseFormData,
+  type FileUploadHandler,
+  type ParseFormDataOptions,
+} from '@remix-run/form-data-parser'
+
+import type { Middleware, RequestContext } from '@remix-run/fetch-router'
+
+export interface FormDataOptions extends ParseFormDataOptions {
+  /**
+   * Set `true` to suppress parse errors. Default is `false`.
+   */
+  suppressErrors?: boolean
+  /**
+   * A function that handles file uploads. It receives a `FileUpload` object and may return any
+   * value that is a valid `FormData` value. Default is `undefined`, which means file uploads are
+   * stored in memory.
+   */
+  uploadHandler?: FileUploadHandler
+}
+
+/**
+ * Middleware that parses `FormData` from the request body and populates `context.formData`.
+ * @param options Options for parsing form data
+ * @returns A middleware function that parses form data
+ */
+export function formData(options?: FormDataOptions): Middleware {
+  let suppressErrors = options?.suppressErrors ?? false
+  let uploadHandler = options?.uploadHandler
+
+  return async (context: RequestContext) => {
+    // Get the method from context to respect any method override middleware
+    let method = context.method
+
+    if (method === 'GET' || method === 'HEAD') {
+      return
+    }
+
+    let contentType = context.headers.get('Content-Type')
+
+    if (
+      contentType == null ||
+      (!contentType.startsWith('multipart/') &&
+        !contentType.startsWith('application/x-www-form-urlencoded'))
+    ) {
+      return
+    }
+
+    try {
+      context.formData = await parseFormData(context.request, options, uploadHandler)
+    } catch (error) {
+      if (!suppressErrors || !(error instanceof FormDataParseError)) {
+        throw error
+      }
+    }
+  }
+}