{"id":17845,"library":"node-uploadx","title":"node-uploadx Resumable Upload Middleware","description":"node-uploadx is a robust Node.js middleware designed for handling resumable file uploads, supporting protocols like Tus (implicitly, through its resumable features). It abstracts away the complexities of chunked uploads, error recovery, and storage management, making it suitable for applications requiring reliable file transfer. The library, currently at version 6.2.1, maintains a regular release cadence, primarily focusing on bug fixes, security enhancements, and minor feature additions as seen in recent patch versions. Key differentiators include its flexible storage options (local filesystem, S3, GCS), integrated metadata handling, built-in validation for file types and sizes, and extensibility for custom scenarios. It integrates seamlessly with popular Node.js frameworks like Express, providing a server-side backbone for client-side upload libraries such as Uppy or ngx-uploadx.","status":"active","version":"6.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/kukhariev/node-uploadx","tags":["javascript","resumable","upload","express","uploadx","middleware","s3","gcloud","typescript"],"install":[{"cmd":"npm install node-uploadx","lang":"bash","label":"npm"},{"cmd":"yarn add node-uploadx","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-uploadx","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used as a server-side framework for integrating uploadx middleware, although uploadx can be used with plain Node.js http.","package":"express","optional":true},{"reason":"Required for S3 cloud storage integration. While not a direct dependency of the core 'node-uploadx' package, it's a necessary dependency for the '@uploadx/s3' module which provides S3 storage capabilities.","package":"@aws-sdk/client-s3"}],"imports":[{"note":"For modern Node.js environments (>=14.18.20), ES Modules are preferred. While CommonJS might still work depending on bundler/Node.js configuration, using `require()` can lead to `ERR_REQUIRE_ESM` with ESM-only builds.","wrong":"const Uploadx = require('node-uploadx');","symbol":"Uploadx","correct":"import { Uploadx } from 'node-uploadx';"},{"note":"DiskStorage is one of the built-in storage adapters for local filesystem uploads. Use named import.","wrong":"const { DiskStorage } = require('node-uploadx');","symbol":"DiskStorage","correct":"import { DiskStorage } from 'node-uploadx';"},{"note":"S3Store is provided as a separate module (`@uploadx/s3`) to keep the core package lightweight and modular. Ensure you install `@uploadx/s3` if using AWS S3.","wrong":"import { S3Store } from 'node-uploadx';","symbol":"S3Store","correct":"import { S3Store } from '@uploadx/s3';"}],"quickstart":{"code":"import express from 'express';\nimport cors from 'cors';\nimport { Uploadx, DiskStorage } from 'node-uploadx';\nimport path from 'path';\n\nconst app = express();\nconst PORT = process.env.PORT || 3003;\nconst UPLOAD_DIR = path.resolve(process.cwd(), 'uploads');\n\n// Ensure the upload directory exists\nimport fs from 'fs';\nif (!fs.existsSync(UPLOAD_DIR)) {\n  fs.mkdirSync(UPLOAD_DIR, { recursive: true });\n}\n\napp.use(cors({ origin: '*', credentials: true })); // Configure CORS appropriately for production\n\napp.use(\n  '/uploads',\n  Uploadx.middleware({\n    storage: new DiskStorage({\n      directory: UPLOAD_DIR,\n      // Optional: Customize file naming\n      filename: (file) => {\n        const ext = path.extname(file.originalName);\n        const name = path.basename(file.originalName, ext);\n        return `${name}-${Date.now()}${ext}`;\n      },\n      // Optional: Set a maximum upload size\n      maxUploadSize: '10GB'\n    }),\n    // Optional: Callback after a file upload is complete\n    onComplete: (file) => {\n      console.log(`Upload complete for file: ${file.originalName} (${file.size} bytes) saved to ${file.filePath}`);\n    },\n    // Optional: Log level\n    logLevel: 'debug'\n  })\n);\n\napp.listen(PORT, () => {\n  console.log(`Upload server listening on port ${PORT}`);\n  console.log(`Uploads will be saved to: ${UPLOAD_DIR}`);\n});","lang":"typescript","description":"This quickstart sets up an Express server with node-uploadx to handle resumable file uploads to a local disk. It demonstrates basic configuration including CORS, a custom upload directory, filename generation, and a completion callback."},"warnings":[{"fix":"Upgrade `node-uploadx` to version `6.1.7` or newer to mitigate the `parse-duration` ReDoS vulnerability.","message":"Versions prior to `6.1.7` of `node-uploadx` were affected by a Regular Expression Denial of Service (ReDoS) vulnerability stemming from the `parse-duration` dependency. This could lead to event loop delays or out-of-memory errors.","severity":"breaking","affected_versions":"<6.1.7"},{"fix":"Upgrade `node-uploadx` to version `6.2.1` or newer to ensure the fix for prototype pollution is applied.","message":"A prototype pollution vulnerability in the `extendObject` utility was patched in version `6.2.1`. Unsanitized input could potentially lead to arbitrary property injection on the `Object.prototype`.","severity":"breaking","affected_versions":"<6.2.1"},{"fix":"Review the `aws-sdk-js-v3` migration guides and ensure your S3 client configurations (e.g., credentials, region, bucket setup) are compatible with the latest SDK version bundled or required by `@uploadx/s3`.","message":"If using a separate `@uploadx/s3` module, updates to the underlying `aws-sdk-js-v3` (as seen in `6.1.6` and `6.1.4` changelogs) might introduce breaking changes in AWS S3 client configuration or API usage, especially if coming from older AWS SDK versions.","severity":"gotcha","affected_versions":">=6.1.4"},{"fix":"Ensure `cors()` middleware is placed before `Uploadx.middleware()` in your Express app. Configure `cors({ origin: 'your-client-domain', credentials: true })` appropriately for production. For development, `origin: '*'` may be used but is insecure for production.","message":"Incorrect middleware ordering or CORS configuration can prevent file uploads from client-side applications. Preflight OPTIONS requests must be handled correctly, and 'Access-Control-Allow-Origin' headers must permit your client's domain.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Convert your consuming file to an ES Module by using `import` statements and ensuring your `package.json` has `\"type\": \"module\"` or the file ends with `.mjs`.","cause":"Attempting to use `require()` to import `node-uploadx` in a CommonJS context when the library or a dependency is published as an ES Module, or when Node.js is configured for strict ESM.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/node-uploadx/dist/index.js from ... not supported."},{"fix":"Ensure `Uploadx.middleware()` is called with its configuration object to return the actual middleware function. Verify the import statement `import { Uploadx } from 'node-uploadx';` is correct and not trying to import a default export as a named one, or vice-versa.","cause":"This error typically occurs in Express if `Uploadx.middleware` is not correctly invoked, or `Uploadx` itself is imported incorrectly and not providing a callable middleware function.","error":"TypeError: Router.use() requires a middleware function but got a Object"},{"fix":"Increase the `maxUploadSize` option in your `Uploadx` configuration, e.g., `maxUploadSize: '5GB'` to allow larger files. Ensure this limit aligns with your server's available resources and security policies.","cause":"The uploaded file's size exceeds the `maxUploadSize` configured in your `Uploadx` storage options. The default limit may be too small for large files.","error":"PayloadTooLargeError: Request body size exceeds file upload limit"},{"fix":"Install and configure the `cors` middleware in your Express application *before* `Uploadx.middleware`. For development, `app.use(cors({ origin: '*' }))` can be used. For production, specify your client's exact origin, e.g., `app.use(cors({ origin: 'http://your-client-domain.com' }))`.","cause":"The client-side application is trying to upload from a different origin (domain, port, protocol) than the server, and the server's Cross-Origin Resource Sharing (CORS) policy does not permit the request.","error":"Access to XMLHttpRequest at 'http://localhost:3003/uploads' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}