@fastify/multipart

When attachFieldsToBody: true is enabled, non-file fields are transformed into a complex object before validation. A field named hello with value world will appear in req.body as:

{
  hello: {
    fieldname: "hello",
    value: "world",
    fieldnameTruncated: false,
    valueTruncated: false,
    fields: body
  }
}

Important: Because this conversion happens before validation, your JSON Schema must account for this structure. For example, to validate the value property, your schema should look like:

hello: {
  properties: {
    value: {
      type: 'string'
    }
  }
}

If a field has a Content-Type header starting with application/json, it will be parsed using JSON.parse.

If a fileSize limit is reached, the plugin can throw a fastify.multipartErrors.RequestFileTooLargeError.

To detect if a limit was reached without catching an error, you can:

1. Listen to data.file.on('limit').
2. Check data.file.truncated after the stream is consumed.
3. Call data.toBuffer() and catch the error.

To disable the automatic throwing behavior (useful for custom error handling), set throwFileSizeLimit: false in the plugin registration or per-request options.

// Check truncated property
const data = await req.file()
await pipeline(data.file, fs.createWriteStream(data.filename))
if (data.file.truncated) {
  // Handle limit reached
}

// OR catch error
try {
  const buffer = await data.toBuffer()
} catch (err) {
  // error is RequestFileTooLargeError
}

When attachFieldsToBody is set to 'keyValues', the multipart body is parsed similarly to application/json or application/x-www-form-urlencoded. In this mode, uploaded files are attached to the body as Buffer objects. This allows you to use standard JSON Schema validation on the req.body.

fastify.register(require('@fastify/multipart'), { attachFieldsToBody: 'keyValues' })

fastify.post('/upload/files', {
  schema: {
    consumes: ['multipart/form-data'],
    body: {
      type: 'object',
      required: ['myFile'],
      properties: {
        // file that gets decoded to string
        myFile: {
          type: 'object',
        },
        hello: {
          type: 'string',
          enum: ['world']
        }
      }
    }
  }
}, function (req, reply) {
  console.log({ body: req.body })
  reply.send('done')
})

To use Zod for multipart validation:

1. Install and configure fastify-type-provider-zod.
2. Set attachFieldsToBody: true when registering @fastify/multipart.
3. (Optional) Use attachFieldsToBody: 'keyValues' to avoid field preprocessing, but note that files will be received as Buffer objects if they are not text/plain.

To enable Swagger/OpenAPI documentation for multipart files, you must:

1. Add require('@fastify/multipart').ajvFilePlugin to your Fastify instance's ajv.plugins configuration.
2. Use the isFile: true property in your JSON Schema for file fields.

const fastify = require('fastify')({
 // ...
  ajv: {
    // Adds the file plugin to help @fastify/swagger schema generation
    plugins: [require('@fastify/multipart').ajvFilePlugin]
  }
})

fastify.register(require("@fastify/multipart"), {
  attachFieldsToBody: true,
});

fastify.post(
  "/upload/files",
  {
    schema: {
      consumes: ["multipart/form-data"],
      body: {
        type: "object",
        required: ["myField"],
        properties: {
          myField: { isFile: true },
        },
      },
    },
  },
  function (req, reply) {
    console.log({ body: req.body });
    reply.send("done");
  }
);

Install the plugin using npm:

npm i @fastify/multipart

When registering the plugin, you can pass a limits object to configure constraints on the uploaded content. These options are passed directly to @fastify/busboy.

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)
  }
});

To enable multipart parsing in your Fastify application, register the @fastify/multipart plugin. You can pass an options object to configure limits such as parts, fileSize, files, and fields.

const fastify = require('fastify')()
const multipart = require('@fastify/multipart')

fastify.register(multipart, {
  limits: {
    fileSize: 1000000 // 1MB
  }
})

Use req.saveRequestFiles() to automatically store all files in the operating system's default temporary directory. The files are removed as soon as the response ends. This method returns an object containing files (an array of file info) and values (parsed non-file fields).

fastify.post('/upload/files', async function (req, reply) {
  const { files, values } = await req.saveRequestFiles()
  // files[0].filepath contains the temp path
  // values.someField.value contains non-file fields
  reply.send()
})