{"id":17674,"library":"graphql-upload-ts","title":"GraphQL Upload for TypeScript","description":"`graphql-upload-ts` is a TypeScript-first library designed to facilitate file uploads within GraphQL applications by providing specialized middleware and an `Upload` scalar type. The current stable version is `2.1.4`, reflecting active development with frequent beta releases. This package distinguishes itself through comprehensive TypeScript support, ensuring type-safety and robust integration across various Node.js frameworks, including Express, Koa, Apollo Server, and GraphQL Yoga. It's built for production environments, featuring efficient file streaming, high test coverage, and compatibility with the Bun runtime. A strong emphasis on security is evident through built-in file validation capabilities, and it supports both CommonJS and ESM module systems for broad project compatibility. Its detailed documentation and example implementations further enhance its usability for developers integrating file upload functionality into their GraphQL APIs.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/meabed/graphql-upload-ts","tags":["javascript","graphql","graphql-upload","graphql-upload-typescript","file-upload","multipart","multipart-request","apollo-server","express","typescript"],"install":[{"cmd":"npm install graphql-upload-ts","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-upload-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-upload-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for GraphQL schema definition and runtime operations.","package":"graphql","optional":false}],"imports":[{"note":"ESM imports are preferred. `graphqlUploadExpress` is the primary middleware for Express-based setups.","wrong":"const { graphqlUploadExpress } = require('graphql-upload-ts');","symbol":"graphqlUploadExpress","correct":"import { graphqlUploadExpress } from 'graphql-upload-ts';"},{"note":"The `GraphQLUpload` scalar must be included in your GraphQL schema's type definitions to handle file inputs.","wrong":"const { GraphQLUpload } = require('graphql-upload-ts');","symbol":"GraphQLUpload","correct":"import { GraphQLUpload } from 'graphql-upload-ts';"},{"note":"This is a TypeScript type interface representing the uploaded file object available in resolvers, used for type hinting.","symbol":"FileUpload","correct":"import { FileUpload } from 'graphql-upload-ts';"}],"quickstart":{"code":"import express from 'express';\nimport { graphqlHTTP } from 'express-graphql';\nimport { graphqlUploadExpress, GraphQLUpload } from 'graphql-upload-ts';\nimport { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';\n\nconst schema = new GraphQLSchema({\n  query: new GraphQLObjectType({\n    name: 'Query',\n    fields: {\n      hello: {\n        type: GraphQLString,\n        resolve: () => 'Hello World',\n      },\n    },\n  }),\n  mutation: new GraphQLObjectType({\n    name: 'Mutation',\n    fields: {\n      uploadFile: {\n        type: GraphQLString,\n        args: {\n          file: { type: GraphQLUpload },\n        },\n        async resolve(_, { file }) {\n          const { filename, createReadStream } = await file;\n          const stream = createReadStream();\n          // Example: Save file to disk or cloud storage\n          // stream.pipe(fs.createWriteStream(`./uploads/${filename}`));\n          console.log(`Processing file: ${filename}`);\n          await new Promise(resolve => stream.on('end', resolve)); // Wait for stream to finish\n          return `File ${filename} uploaded successfully`;\n        },\n      },\n    },\n  }),\n});\n\nconst app = express();\n\n// Important: graphqlUploadExpress middleware must come BEFORE graphqlHTTP\napp.use(\n  '/graphql',\n  graphqlUploadExpress({ maxFileSize: 10000000, maxFiles: 10 }), // 10 MB limit per file, 10 files max\n  graphqlHTTP({\n    schema,\n    graphiql: true, // Enable GraphiQL for easy testing\n  }),\n);\n\nconst PORT = process.env.PORT ?? 4000;\napp.listen(PORT, () => {\n  console.log(`GraphQL server running on http://localhost:${PORT}/graphql`);\n});","lang":"typescript","description":"This quickstart demonstrates setting up a basic GraphQL server with Express and `graphql-upload-ts` to handle file upload mutations. It configures the necessary middleware and defines a simple schema with an `uploadFile` mutation."},"warnings":[{"fix":"Ensure `app.use(graphqlUploadExpress({ ... }));` is declared and invoked prior to `app.use('/graphql', graphqlHTTP({ ... }));` or your Apollo Server integration.","message":"The `graphqlUploadExpress` middleware must be applied *before* your main GraphQL HTTP middleware (e.g., `express-graphql`, Apollo Server's middleware) to correctly parse multipart requests. Incorrect order will prevent file uploads from being processed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js runtime to version 16.0.0 or higher to meet the minimum engine requirements.","message":"The library requires Node.js version 16 or newer. Running on older Node.js environments may lead to unexpected runtime errors or instability due to reliance on modern JavaScript features and API availability.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Explicitly configure these limits in the `graphqlUploadExpress` options. For example: `graphqlUploadExpress({ maxFileSize: 20000000, maxFiles: 5 })` for 20MB files and 5 files maximum. Implement custom stream processing for extremely large files to avoid buffering entirely.","message":"By default, `graphql-upload-ts` has limits for file size (`maxFileSize`), number of files (`maxFiles`), and total fields (`maxFieldSize`). Exceeding these limits, especially for large files or numerous uploads, can lead to server crashes or resource exhaustion (e.g., out-of-memory errors).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `GraphQLUpload` is imported from `graphql-upload-ts` and added to your schema's type definitions, e.g., in a `types` array for `GraphQLSchema` or explicitly referenced in your schema language definition.","cause":"The `GraphQLUpload` scalar type was not included or correctly referenced in your GraphQL schema definition.","error":"Error: Unknown type \"Upload\". Did you mean \"Boolean\" or \"String\"?"},{"fix":"Verify that your client is sending a `Content-Type: multipart/form-data` header. Double-check that `graphqlUploadExpress` is correctly used and placed *before* your primary GraphQL HTTP handler middleware.","cause":"The client request sent was not `multipart/form-data`, or the `graphqlUploadExpress` middleware was not correctly applied or ordered.","error":"Error: Request must be a multipart request."},{"fix":"Confirm that the `file` argument in your GraphQL mutation is correctly typed as `GraphQLUpload` in the schema. Ensure the client's multipart request correctly maps the file input to the `file` argument in the GraphQL query variables.","cause":"The `file` argument in your resolver is `undefined` or not the expected `FileUpload` object, typically indicating a problem with the multipart request parsing or schema definition.","error":"TypeError: Cannot read properties of undefined (reading 'createReadStream')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}