{"id":47970,"library":"graphql-upload-commonjs","title":"graphql-upload (CommonJS)","description":"Middleware and Upload scalar for GraphQL multipart requests (file uploads via queries and mutations) in Node.js. Version 16.0.2-beta.3. Supports Koa, Express, and Apollo servers. Beta release with CommonJS support. Key differentiators: direct integration with graphql-upload ecosystem, supports file deduplication, streaming uploads, and custom middleware via processRequest. Peer dependencies: @types/express, @types/koa, graphql ^16.3.0. Requires Node ^14.17.0 || ^16.0.0 || >= 18.0.0.","status":"active","version":"16.0.2-beta.3","language":"javascript","source_language":"en","source_url":"https://github.com/jaydenseric/graphql-upload","tags":["javascript","graphql","upload","file","multipart","request","server","middleware","koa"],"install":[{"cmd":"npm install graphql-upload-commonjs","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-upload-commonjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-upload-commonjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for GraphQL schema building and execution","package":"graphql","optional":false},{"reason":"Peer dependency for Express middleware types when using TypeScript","package":"@types/express","optional":true},{"reason":"Peer dependency for Koa middleware types when using TypeScript","package":"@types/koa","optional":true}],"imports":[{"note":"ESM import is preferred but named export also works with CommonJS require.","wrong":"const graphqlUploadKoa = require('graphql-upload-commonjs').graphqlUploadKoa","symbol":"graphqlUploadKoa","correct":"import { graphqlUploadKoa } from 'graphql-upload-commonjs'"},{"note":"Both ESM and CommonJS supported but ESM import is recommended.","wrong":"const { graphqlUploadExpress } = require('graphql-upload-commonjs')","symbol":"graphqlUploadExpress","correct":"import { graphqlUploadExpress } from 'graphql-upload-commonjs'"},{"note":"Use for custom middleware; exports both as named export.","wrong":"const processRequest = require('graphql-upload-commonjs').processRequest","symbol":"processRequest","correct":"import { processRequest } from 'graphql-upload-commonjs'"},{"note":"GraphQLUpload is a named export, not default.","wrong":"import GraphQLUpload from 'graphql-upload-commonjs'","symbol":"GraphQLUpload","correct":"import { GraphQLUpload } from 'graphql-upload-commonjs'"}],"quickstart":{"code":"import express from 'express';\nimport { graphqlHTTP } from 'express-graphql';\nimport { buildSchema, GraphQLScalarType } from 'graphql';\nimport { graphqlUploadExpress, GraphQLUpload } from 'graphql-upload-commonjs';\n\nconst schema = buildSchema(`\n  scalar Upload\n\n  type File {\n    filename: String\n    mimetype: String\n    encoding: String\n  }\n\n  type Query {\n    uploads: [File]\n  }\n\n  type Mutation {\n    singleUpload(file: Upload!): File!\n  }\n`);\n\nconst resolvers = {\n  Upload: GraphQLUpload,\n  Query: {\n    uploads: () => []\n  },\n  Mutation: {\n    singleUpload: async (parent, { file }) => {\n      const { createReadStream, filename, mimetype, encoding } = await file;\n      const stream = createReadStream();\n      // Process stream...\n      return { filename, mimetype, encoding };\n    }\n  }\n};\n\nconst app = express();\napp.use(graphqlUploadExpress({ maxFileSize: 10000000, maxFiles: 10 }));\napp.use('/graphql', graphqlHTTP({ schema, rootValue: resolvers, graphiql: true }));\napp.listen(4000, () => console.log('Server running on http://localhost:4000/graphql'));","lang":"typescript","description":"Express server with graphql-upload middleware handling single file upload mutation."},"warnings":[{"fix":"Update Node to ^14.17.0 || ^16.0.0 || >=18.0.0; use named imports from 'graphql-upload-commonjs'.","message":"Version 16.0.0 dropped support for Node <14.17.0, removed deprecated exports, and changed export structure","severity":"breaking","affected_versions":">=16.0.0"},{"fix":"Switch to 'graphql-upload-commonjs'.","message":"The old package 'graphql-upload' without CommonJS support is deprecated; use 'graphql-upload-commonjs' for CommonJS compatibility","severity":"deprecated","affected_versions":">=16.0.0"},{"fix":"Use import { GraphQLUpload } from 'graphql-upload-commonjs'.","message":"GraphQLUpload is a named export, not default; attempting to import it as default will result in undefined","severity":"gotcha","affected_versions":">=16.0.0"},{"fix":"Always provide an options object with maxFileSize and maxFiles to avoid unbounded resource usage.","message":"processRequest must be called with the correct signature; missing options can cause memory leaks","severity":"gotcha","affected_versions":">=16.0.0"}],"env_vars":null,"search_vec":"'14.17.0':62 '16.0.0':63 '16.0.2':22 '16.3.0':59 '18.0.0':64 'apollo':28 'beta':30 'beta.3':23 'commonj':4,33 'custom':50 'dedupl':46 'depend':55 'differenti':36 'direct':37 'ecosystem':43 'express':26 'file':13,45,68 'graphql':2,10,41,58,66 'graphql-upload':1,40 'integr':38 'javascript':65 'key':35 'koa':25,73 'middlewar':5,51,72 'multipart':11,69 'mutat':18 'node':61 'node.js':20 'peer':54 'processrequest':53 'queri':16 'releas':31 'request':12,70 'requir':60 'scalar':8 'server':29,71 'stream':47 'support':24,34,44 'types/express':56 'types/koa':57 'upload':3,7,14,42,48,67 'version':21 'via':15,52","created_at":"2026-06-07T16:54:16.050296+00:00","updated_at":"2026-06-07T16:54:16.050296+00:00","problems":[{"fix":"Run npm install graphql-upload-commonjs graphql","cause":"Package not installed or version mismatch","error":"Cannot find module 'graphql-upload-commonjs'"},{"fix":"Use await file before destructuring: const { createReadStream, filename, mimetype, encoding } = await file;","cause":"Resolver not awaited the file promise","error":"TypeError: Cannot destructure property 'createReadStream' of 'file' as it is undefined."},{"fix":"Use import { GraphQLUpload } from 'graphql-upload-commonjs'","cause":"Imported GraphQLUpload incorrectly as default instead of named export","error":"GraphQLUpload is not a constructor"},{"fix":"Set the resolvers.Upload property to GraphQLUpload","cause":"GraphQLUpload not assigned to the Upload scalar in schema resolvers","error":"Expected Upload to be a GraphQL scalar type"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/MazueraAlvaro/graphql-upload-common-js#readme","github":"https://github.com/jaydenseric/graphql-upload","docs":null,"changelog":null,"pypi":null,"npm":"graphql-upload-commonjs","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}