Registry /
http-networking / graphql-server-express-upload
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
graphqlExpressUpload
✓ import graphqlExpressUpload from 'graphql-server-express-upload';
✗ import { graphqlExpressUpload } from 'graphql-server-express-upload';
This is a default export. For CommonJS, use `const graphqlExpressUpload = require('graphql-server-express-upload').default;`.
UploadedFile
✓ scalar UploadedFile
This is a GraphQL Schema Definition Language (SDL) scalar type, not a JavaScript import. It must be defined in your `.graphql` files or `typeDefs` string.
Kind
✓ import { Kind } from 'graphql';
✗ import { Kind } from 'graphql/language/kinds';
The `Kind` enum is used within the example `parseJSONLiteral` resolver function to identify GraphQL AST node types. It's imported from the main `graphql` package.
Demonstrates setting up an Express server with `graphql-server-express-upload`, configuring `multer` for multipart processing, defining the `UploadedFile` scalar in the schema, and providing its custom resolver.
import express from 'express';
import { makeExecutableSchema } from '@graphql-tools/schema';
import { graphqlExpress, graphiqlExpress } from 'graphql-server-express';
import graphqlExpressUpload from 'graphql-server-express-upload';
import multer from 'multer';
import { Kind } from 'graphql';
const app = express();
const port = 4000;
// Multer setup for file uploads
const upload = multer({
dest: '/tmp/uploads', // Ensure this directory exists or create it
});
// GraphQL Schema Definition
const typeDefs = `
scalar UploadedFile
type ProfilePicture {
id: Int!
url: String
thumb: String
square: String
small: String
medium: String
large: String
full: String
}
type Query {
hello: String
}
type Mutation {
uploadProfilePicture(id: Int!, files: [UploadedFile!]!): ProfilePicture
}
`;
// Utility for UploadedFile scalar resolver (as shown in package README)
function parseJSONLiteral(ast) {
switch (ast.kind) {
case Kind.STRING:
case Kind.BOOLEAN:
return ast.value;
case Kind.INT:
case Kind.FLOAT:
return parseFloat(ast.value);
case Kind.OBJECT: {
const value = Object.create(null);
ast.fields.forEach(field => {
value[field.name.value] = parseJSONLiteral(field.value);
});
return value;
}
case Kind.LIST:
return ast.values.map(parseJSONLiteral);
default:
return null;
}
}
// GraphQL Resolvers
const resolvers = {
UploadedFile: {
__parseLiteral: parseJSONLiteral,
__serialize: value => value,
__parseValue: value => value,
},
Query: {
hello: () => 'Hello from GraphQL!',
},
Mutation: {
async uploadProfilePicture(root, { id, files }, context) {
console.log('Received upload for profile picture:', { id, files });
// 'files' here would be an array of objects provided by Multer/graphqlExpressUpload
// In a real app, process these files (e.g., save to disk, cloud storage).
const uploadedFile = files[0]; // Example: assuming one file
return {
id,
url: `http://example.com/uploads/${uploadedFile?.filename || 'dummy.jpg'}`,
thumb: `http://example.com/thumbs/${uploadedFile?.filename || 'dummy.jpg'}`,
square: `http://example.com/square/${uploadedFile?.filename || 'dummy.jpg'}`,
small: `http://example.com/small/${uploadedFile?.filename || 'dummy.jpg'}`,
medium: `http://example.com/medium/${uploadedFile?.filename || 'dummy.jpg'}`,
large: `http://example.com/large/${uploadedFile?.filename || 'dummy.jpg'}`,
full: `http://example.com/full/${uploadedFile?.filename || 'dummy.jpg'}`
};
},
},
};
const schema = makeExecutableSchema({ typeDefs, resolvers });
// Express app setup for GraphQL endpoint
app.use(
'/graphql',
upload.array('files'), // Multer middleware to handle 'files' input field
graphqlExpressUpload({ endpointURL: '/graphql' }), // THIS PACKAGE'S MIDDLEWARE
graphqlExpress((req) => ({
schema,
context: {
req, // Access to the original request
},
}))
);
// GraphiQL endpoint for testing
app.use(
'/graphiql',
graphiqlExpress({
endpointURL: '/graphql',
})
);
app.listen(port, () => {
console.log(`Server running on http://localhost:${port}`);
console.log(`GraphQL endpoint: http://localhost:${port}/graphql`);
console.log(`GraphiQL endpoint: http://localhost:${port}/graphiql`);
});
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'query') / req.body.query is undefined
The `graphqlExpressUpload` middleware or `multer` is not correctly placed or configured in the Express middleware chain, preventing the GraphQL query from being parsed.
fixEnsure `multer` middleware (e.g., `upload.array('files')`) is applied *before* `graphqlExpressUpload`, and `graphqlExpressUpload` is *before* `graphqlExpress`. Also, verify the `endpointURL` configuration matches your GraphQL endpoint path. Unknown type 'UploadedFile'. Did you mean 'Upload'? (or similar type system errors)
The `UploadedFile` scalar type has not been defined in your GraphQL schema or its associated resolver is missing or incorrectly registered with your GraphQL server.
fixAdd `scalar UploadedFile` to your GraphQL schema definition (typeDefs) and ensure the `UploadedFile` resolver (with `__parseLiteral`, `__serialize`, `__parseValue` methods) is correctly provided to your GraphQL server setup.
ApolloError: Variable "$files" got invalid value [object Object]; Expected type UploadedFile! (or similar type mismatch for file arguments)
The client-side is not sending files in the expected `multipart/form-data` format, or the `UploadedFile` scalar resolver is misconfigured, leading to a type mismatch during validation.
fixVerify that your client-side code uses a network interface (e.g., `apollo-upload-network-interface` for older Apollo Client versions, or modern `apollo-link-http` with `apollo-upload-client`) that correctly handles `multipart/form-data`. Additionally, double-check the `UploadedFile` resolver logic for any issues.
Audit
Dependencies
multerrequiredRequired for parsing multipart/form-data requests containing file uploads.
graphql-server-expressrequiredThis middleware is specifically designed to function as an enhancement for graphql-server-express, which is now deprecated.
graphqlrequiredUsed for GraphQL schema definition, type parsing (e.g., Kind enum in resolvers), and core GraphQL functionality.