Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import MercuriusGQLUpload from 'mercurius-upload'
✗ const MercuriusGQLUpload = require('mercurius-upload')
Plugin uses default export. CommonJS require works, but TypeScript might need esModuleInterop.
GraphQLUpload
✓ import { GraphQLUpload } from 'graphql-upload-minimal'
✗ import { GraphQLUpload } from 'mercurius-upload'
GraphQLUpload scalar is exported from graphql-upload-minimal package, not from mercurius-upload.
FastifyInstance.register
✓ fastify.register(MercuriusGQLUpload, { maxFileSize: 5 * 1024 * 1024 })
✗ fastify.use(MercuriusGQLUpload)
Must use register() method, not middleware pattern.
Shows how to set up a Fastify+Mercurius server with GraphQL file upload support using mercurius-upload and graphql-upload-minimal.
import Fastify from 'fastify';
import mercurius from 'mercurius';
import MercuriusGQLUpload from 'mercurius-upload';
import { GraphQLUpload } from 'graphql-upload-minimal';
import { writeFile, mkdir } from 'fs/promises';
import { join } from 'path';
import { v4 as uuidv4 } from 'uuid';
const schema = `
scalar Upload
type Query { ping: String }
type Mutation { uploadFile(file: Upload!): Boolean }
`;
const resolvers = {
Upload: GraphQLUpload,
Query: { ping: () => 'pong' },
Mutation: {
uploadFile: async (_, { file }) => {
const { filename, createReadStream } = await file;
const stream = createReadStream();
const uploadDir = join(process.cwd(), 'uploads');
await mkdir(uploadDir, { recursive: true });
const path = join(uploadDir, `${uuidv4()}-${filename}`);
await new Promise((resolve, reject) => {
const writable = writeFile(path, '');
stream.pipe(writable);
stream.on('end', resolve);
stream.on('error', reject);
});
return true;
},
},
};
const app = Fastify();
app.register(MercuriusGQLUpload, { maxFileSize: 10 * 1024 * 1024 });
app.register(mercurius, { schema, resolvers, graphiql: true });
app.listen({ port: 4000 }, () => console.log('Server running on http://localhost:4000'));
Errors
Common errors & fixes
FastifyError: the route 'POST /graphql' already exists
Registering mercurius-upload before mercurius or vice versa incorrectly.
fixEnsure mercurius-upload is registered before mercurius: fastify.register(MercuriusGQLUpload); fastify.register(mercurius, {...}); TypeError: (intermediate value).createReadStream is not a function
Accessing createReadStream directly on the uploaded file promise without awaiting it.
fixUse `const { createReadStream } = await file;` or `const stream = (await file).createReadStream();` Cannot find module 'graphql-upload-minimal'
graphql-upload-minimal is not installed.
fixInstall graphql-upload-minimal: npm install graphql-upload-minimal
Argument of type 'typeof import(...)' is not assignable to parameter of type 'FastifyPluginAsync'
TypeScript issues with default import and module resolution.
fixEnsure esModuleInterop is enabled in tsconfig.json, or use: import * as MercuriusGQLUpload from 'mercurius-upload'
Audit
Dependencies
graphqlrequiredpeer dependency; required by mercurius and for GraphQL scalar handling
graphql-upload-minimalrequiredruntime dependency providing the upload processing logic