const fastify = require('fastify')()const fs = require('node:fs')const { pipeline } = require('node:stream/promises')fastify.register(require('@fastify/multipart'))fastify.post('/', async function (req, reply) { // process a single file // also, consider that if you allow to upload multiple files // you must consume all files otherwise the promise will never fulfill const data = await req.file() data.file // stream data.fields // other parsed parts data.fieldname data.filename data.encoding data.mimetype // to accumulate the file in memory! Be careful! // // await data.toBuffer() // Buffer // // or await pipeline(data.file, fs.createWriteStream(data.filename)) // be careful of permission issues on disk and not overwrite // sensitive files that could cause security risks // also, consider that if the file stream is not consumed, the promise will never fulfill reply.send()})fastify.listen({ port: 3000 }, err => { if (err) throw err console.log(`server listening on ${fastify.server.address().port}`)})
Note about data.fields: busboy consumes the multipart in serial order (stream). Therefore, the order of form fields is VERY IMPORTANT to how @fastify/multipart can display the fields to you.
We would recommend you place the value fields first before any of the file fields.
It will ensure your fields are accessible before it starts consuming any files.
If you cannot control the order of the placed fields, be sure to read data.fieldsAFTER consuming the stream, or it will only contain the fields parsed at that moment.
You can also pass optional arguments to @fastify/busboy when registering with Fastify. This is useful for setting limits on the content that can be uploaded. A full list of available options can be found in the @fastify/busboy documentation.
fastify.register(require('@fastify/multipart'), { limits: { fieldNameSize: 100, // Max field name size in bytes fieldSize: 100, // Max field value size in bytes fields: 10, // Max number of non-file fields fileSize: 1000000, // For multipart forms, the max file size in bytes files: 1, // Max number of file fields headerPairs: 2000, // Max number of header key=>value pairs parts: 1000 // For multipart forms, the max number of parts (fields + files) }});
For security reasons, @fastify/multipart defaults parts to 1000 and fileSize to the Fastify bodyLimit (1 MiB by default).
Note: multipart requests are parsed by a dedicated streaming parser and do not go through Fastify's bodyLimit enforcement. bodyLimit is only used to compute the per-file fileSize default; it is not enforced as an aggregate limit across the whole multipart payload. A single request can therefore contain more data than bodyLimit once spread across many fields and files, and the route-level bodyLimit is not applied to the multipart parser. If you need to bound the total request size, set explicit fieldSize, fields, files, parts, and fileSize limits and/or enforce a request-size limit upstream.
Note: if the file stream that is provided by data.file is not consumed, like in the example below with the usage of pipeline, the promise will not be fulfilled at the end of the multipart processing.
This behavior is inherited from @fastify/busboy.
Note: if you set a fileSize limit and you want to know if the file limit was reached you can:
listen to data.file.on('limit')
or check at the end of the stream the property data.file.truncated
or call data.file.toBuffer() and wait for the error to be thrown
const data = await req.file()await pipeline(data.file, fs.createWriteStream(data.filename))if (data.file.truncated) { // you may need to delete the part of the file that has been saved on disk // before the `limits.fileSize` has been reached reply.send(new fastify.multipartErrors.FilesLimitError());}// ORconst data = await req.file()try { const buffer = await data.toBuffer()} catch (err) { // fileSize limit reached!}
Additionally, you can pass per-request options to the req.file, req.files, req.saveRequestFiles or req.parts function.
fastify.post('/', async function (req, reply) { const parts = req.files() for await (const part of parts) { await pipeline(part.file, fs.createWriteStream(part.filename)) } reply.send()})
Handle multiple file streams and fields
fastify.post('/upload/raw/any', async function (req, reply) { const parts = req.parts() for await (const part of parts) { if (part.type === 'file') { await pipeline(part.file, fs.createWriteStream(part.filename)) } else { // part.type === 'field console.log(part) } } reply.send()})
Accumulating the entire file in memory
fastify.post('/upload/raw/any', async function (req, reply) { const data = await req.file() const buffer = await data.toBuffer() // upload to S3 reply.send()})
Upload files to disk and work with temporary file paths
This will store all files in the operating system's default directory for temporary files. As soon as the response ends all files are removed.
fastify.post('/upload/files', async function (req, reply) { // stores files to tmp dir and returns files + parsed values const { files, values } = await req.saveRequestFiles() files[0].type // "file" files[0].filepath files[0].fieldname files[0].filename files[0].encoding files[0].mimetype files[0].fields // other parsed parts values.hello?.value // non-file fields are available even if no file was uploaded reply.send()})
Handle file size limitation
If you set a fileSize limit, it can throw a RequestFileTooLargeError error when limit reached.
If you want to fallback to the handling before 4.0.0, you can disable the throwing behavior by passing throwFileSizeLimit.
Note: It will not affect the behavior of saveRequestFiles()
This allows you to parse all fields automatically and assign them to the request.body. By default, files are accumulated in memory (Be careful!) to buffer objects. Uncaught errors are handled by Fastify.
fastify.register(require('@fastify/multipart'), { attachFieldsToBody: true })fastify.post('/upload/files', async function (req, reply) { const uploadValue = await req.body.upload.toBuffer() // access files const fooValue = req.body.foo.value // other fields const body = Object.fromEntries( Object.keys(req.body).map((key) => [key, req.body[key].value]) ) // Request body in key-value pairs, like req.body in Express const formData = await req.formData() console.log(formData)})
Request body key-value pairs can be assigned directly using attachFieldsToBody: 'keyValues'. Field values, including file buffers, will be attached to the body object.
fastify.register(require('@fastify/multipart'), { attachFieldsToBody: 'keyValues' })fastify.post('/upload/files', async function (req, reply) { const uploadValue = req.body.upload // access file as buffer const fooValue = req.body.foo // other fields})
You can also define an onFile handler to avoid accumulating all files in memory.
async function onFile(part) { // you have access to original request via `this` console.log(this.id) await pipeline(part.file, fs.createWriteStream(part.filename))}fastify.register(require('@fastify/multipart'), { attachFieldsToBody: true, onFile })fastify.post('/upload/files', async function (req, reply) { const fooValue = req.body.foo.value // other fields})
The onFile handler can also be used with attachFieldsToBody: 'keyValues' in order to specify how file buffer values are decoded.
async function onFile(part) { const buff = await part.toBuffer() const decoded = Buffer.from(buff.toString(), 'base64').toString() part.value = decoded // set `part.value` to specify the request body value}fastify.register(require('@fastify/multipart'), { attachFieldsToBody: 'keyValues', onFile })fastify.post('/upload/files', async function (req, reply) { const uploadValue = req.body.upload // access file as base64 string const fooValue = req.body.foo // other fields})
Note: if you assign all fields to the body and don't define an onFile handler, you won't be able to read the files through streams, as they are already read and their contents are accumulated in memory.
You can only use the toBuffer method to read the content.
If you try to read from a stream and pipe to a new file, you will obtain an empty new file.
JSON Schema body validation
When the attachFieldsToBody parameter is set to 'keyValues', JSON Schema validation on the body will behave similarly to application/json and application/x-www-form-urlencoded content types. Additionally, uploaded files will be attached to the body as Buffer objects.
If you enable attachFieldsToBody: true and set sharedSchemaId a shared JSON Schema is added, which can be used to validate parsed multipart fields.
const opts = { attachFieldsToBody: true, sharedSchemaId: '#mySharedSchema'}fastify.register(require('@fastify/multipart'), opts)fastify.post('/upload/files', { schema: { consumes: ['multipart/form-data'], body: { type: 'object', required: ['myField'], properties: { // field that uses the shared schema myField: { $ref: '#mySharedSchema'}, // or another field that uses the shared schema myFiles: { type: 'array', items: fastify.getSchema('mySharedSchema') }, // or a field that doesn't use the shared schema hello: { properties: { value: { type: 'string', enum: ['male'] } } } } } }}, function (req, reply) { console.log({ body: req.body }) reply.send('done')})
If provided, the sharedSchemaId parameter must be a string ID and a shared schema will be added to your fastify instance so you will be able to apply the validation to your service (like in the example mentioned above).
Multipart fields are converted before validation. Repeated field names are grouped into arrays, but a field sent once remains a single field object. This means AJV coerceTypes: 'array' will not wrap a single multipart field object in an array for a schema like myFiles: { type: 'array', items: fastify.getSchema('#mySharedSchema') }. If a field accepts one or more values, validate both the single-value and repeated-value shapes, then normalize the value in your handler if needed:
If you want to use @fastify/multipart with @fastify/swagger and @fastify/swagger-ui you must add a new type called isFile and use a custom instance of a validator compiler Docs.
It is important to know that this conversion happens BEFORE the field is validated, so keep that in mind when writing the JSON schema for validation for fields that don't use the shared schema. The schema for validation for the field mentioned above should look like this:
Make sure the attachFieldsToBody option is set to true when registering the @fastify/multipart plugin.
You can use attachFieldsToBody: "keyValues" to avoid another fields preprocessing, but in that case, you will receive a Buffer for files that are not text/plain.
After setup, you can validate your request body using a Zod schema as usual.
We export all custom errors via a server decorator fastify.multipartErrors. This is useful if you want to react to specific errors. They are derived from @fastify/error and include the correct statusCode property.