{"id":17769,"library":"koa2-formidable","title":"Koa2 Formidable Middleware","description":"koa2-formidable is a Koa 2 middleware designed to parse multipart/form-data requests, primarily for file uploads and complex form submissions. It acts as a wrapper around the popular `formidable` library, simplifying its integration into Koa applications. The package is currently at version 1.0.3 and has not seen any updates or releases in over five years, indicating it is no longer actively maintained. This contrasts sharply with the underlying `formidable` library, which is actively developed and has moved to major versions 3 and 4, introducing ESM support, modern Node.js stream compatibility, and crucial security updates. As such, `koa2-formidable` relies on an outdated version of `formidable`, making it unsuitable for modern Koa projects due to potential security vulnerabilities, lack of current features, and compatibility issues with newer Node.js runtimes.","status":"abandoned","version":"1.0.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/GaryChangCN/koa2-formidable","tags":["javascript","formidable","koa2"],"install":[{"cmd":"npm install koa2-formidable","lang":"bash","label":"npm"},{"cmd":"yarn add koa2-formidable","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa2-formidable","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for parsing multipart/form-data requests.","package":"formidable","optional":false}],"imports":[{"note":"This package is CommonJS-only, reflecting its age and lack of maintenance. It does not provide ESM exports.","symbol":"formidable","correct":"const formidable = require('koa2-formidable');"}],"quickstart":{"code":"const Koa = require('koa');\nconst Router = require('@koa/router');\nconst formidable = require('koa2-formidable');\nconst path = require('path');\nconst fs = require('fs');\n\nconst app = new Koa();\nconst router = new Router();\n\n// Apply koa2-formidable middleware with custom options for formidable\n// Ensure the upload directory exists\nconst uploadDir = path.join(__dirname, 'uploads');\nif (!fs.existsSync(uploadDir)) {\n  fs.mkdirSync(uploadDir);\n}\n\napp.use(formidable({\n  uploadDir: uploadDir,\n  keepExtensions: true,\n  multiples: true\n}));\n\nrouter.post('/upload', async (ctx, next) => {\n  // Access parsed fields and files from ctx.request\n  const { body, files } = ctx.request;\n\n  console.log('Received fields:', body);\n  console.log('Received files:', files);\n\n  let fileInfo = {};\n  if (files) {\n    if (Array.isArray(files.uploadFile)) {\n      fileInfo = files.uploadFile.map(f => ({ name: f.name, path: f.path, size: f.size }));\n    } else if (files.uploadFile) {\n      fileInfo = { name: files.uploadFile.name, path: files.uploadFile.path, size: files.uploadFile.size };\n    }\n  }\n\n  ctx.body = {\n    message: 'File upload successful!',\n    fields: body,\n    files: fileInfo\n  };\n});\n\napp.use(router.routes()).use(router.allowedMethods());\n\napp.listen(3000, () => {\n  console.log('Koa server listening on http://localhost:3000');\n  console.log('Use a tool like Postman or curl to POST multipart/form-data to /upload.');\n  console.log('Example: curl -X POST -F \"username=test\" -F \"uploadFile=@./some-file.txt\" http://localhost:3000/upload');\n});","lang":"javascript","description":"This quickstart demonstrates how to set up `koa2-formidable` in a Koa application to handle multipart/form-data uploads, including file and field parsing, and how to access the processed data via `ctx.request.body` and `ctx.request.files`."},"warnings":[{"fix":"Migrate to actively maintained Koa body parsing middleware like `@koa/body` or `koa-body`, which use up-to-date versions of `formidable` or other robust parsers. If direct `formidable` integration is preferred, use the `formidable` library directly with careful implementation, passing `ctx.req` (Node.js Request) to `formidable`'s `parse` method.","message":"The package `koa2-formidable` has not been updated in over five years and relies on a significantly outdated version of `formidable`. This older `formidable` version is deprecated and known to contain security vulnerabilities if not implemented with extreme care, and it lacks features present in modern `formidable` (v3+).","severity":"breaking","affected_versions":"1.0.3"},{"fix":"For new projects or existing ESM projects, prefer middlewares that offer native ESM support. If forced to use, integrate via `import pkg = require('pkg')` in TypeScript or dynamic `import()` in JavaScript, though this is generally discouraged for middleware.","message":"`koa2-formidable` is a CommonJS-only package. It cannot be directly `import`ed in an ESM-first Node.js project without specific configuration or a build step, which adds unnecessary complexity to modern applications.","severity":"gotcha","affected_versions":"1.0.3"},{"fix":"Avoid using this package in production. If currently in use, plan for migration to an actively maintained alternative to ensure stability, security, and long-term compatibility.","message":"Given its abandoned status, `koa2-formidable` will not receive bug fixes, performance improvements, or compatibility updates for newer Node.js versions or Koa releases. This can lead to runtime errors or unexpected behavior as the ecosystem evolves.","severity":"gotcha","affected_versions":"1.0.3"},{"fix":"For fine-grained control over `formidable`'s capabilities, consider using the `formidable` library directly within your Koa routes. This allows direct access to `formidable`'s `IncomingForm` instance and its full API.","message":"The `formidable` options passed to `koa2-formidable` might not fully expose or correctly configure all modern `formidable` features, especially those introduced in `formidable` v2 or v3, leading to limitations in how file uploads and fields can be handled (e.g., streaming to cloud storage, advanced progress tracking).","severity":"gotcha","affected_versions":"1.0.3"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"This warning cannot be fixed within `koa2-formidable` itself. The only resolution is to replace `koa2-formidable` with an actively maintained Koa body parsing middleware that uses a current version of `formidable` (v3+) or an alternative parser. Consider `koa-body` or `@koa/body`.","cause":"This warning appears because `koa2-formidable` depends on a very old and deprecated version of the `formidable` library, which is no longer maintained and has known security vulnerabilities.","error":"WARN deprecated formidable@1.x.x: Please upgrade to latest, formidable@v2 or formidable@v3! Check these notes: https://bit.ly/2ZEqIau"},{"fix":"Ensure your file is treated as a CommonJS module (e.g., a `.js` file without `\"type\": \"module\"` in `package.json`). Alternatively, if your project is ESM, you must use dynamic `import()`: `const formidable = await import('koa2-formidable');`, though this is generally not recommended for middleware due to its asynchronous nature.","cause":"Attempting to `require('koa2-formidable')` in an ECMAScript Module (ESM) context (e.g., in a file with `\"type\": \"module\"` in `package.json` or a `.mjs` file). This package is CommonJS-only.","error":"TypeError: require is not a function"},{"fix":"Ensure you are passing the `maxFieldsSize` and `maxFileSize` options correctly to the `formidable` middleware. For example: `app.use(formidable({ maxFieldsSize: 20 * 1024 * 1024, maxFileSize: 200 * 1024 * 1024 }));` (for 20MB fields and 200MB files). If problems persist, this may indicate a limitation of the old `formidable` version, requiring migration to a modern alternative.","cause":"The default `maxFieldsSize` (or `maxFileSize`) of the outdated `formidable` version used by `koa2-formidable` is too low for your application's needs, or the options are not being correctly applied.","error":"Error: Max fields size exceeded. (or similar errors related to request size limits)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}