nestjs-busboy

File upload support for NestJS that works with both the Fastify and Express adapters, built directly on @fastify/busboy (the underlying multipart parser).

This package replaces @nest-lab/fastify-multer, which depends on the unmaintained fastify-multer library and does not support Fastify v5.

Installation

npm i nestjs-busboy
yarn add nestjs-busboy
pnpm i nestjs-busboy

Usage

Use this exactly like you would the MulterModule from @nestjs/platform-express. The same interceptors, storage engines, and options are supported.

You must import BusboyModule somewhere in your application so that the multipart/form-data content-type parser is registered with Fastify (on Express this step is a no-op).

Basic setup

import { BusboyModule } from 'nestjs-busboy';

@Module({
  imports: [BusboyModule],
})
export class AppModule {}

Module-level options

import { BusboyModule, memoryStorage } from 'nestjs-busboy';

@Module({
  imports: [
    BusboyModule.register({
      storage: memoryStorage(),
    }),
  ],
})
export class AppModule {}

Async options

@Module({
  imports: [
    BusboyModule.registerAsync({
      useFactory: (config: ConfigService) => ({
        dest: config.get('UPLOAD_DIR'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Interceptors

All interceptors accept an optional localOptions argument that is merged with module-level options.

import {
  AnyFilesInterceptor,
  FileFieldsInterceptor,
  FileInterceptor,
  FilesInterceptor,
  NoFilesInterceptor,
  memoryStorage,
} from 'nestjs-busboy';

@Controller('upload')
export class UploadController {
  // Single file from field "file"
  @Post('single')
  @UseInterceptors(FileInterceptor('file', { storage: memoryStorage() }))
  uploadSingle(@UploadedFile() file: Express.Multer.File) { ... }

  // Up to 10 files from field "files"
  @Post('multiple')
  @UseInterceptors(FilesInterceptor('files', 10, { storage: memoryStorage() }))
  uploadMultiple(@UploadedFiles() files: Express.Multer.File[]) { ... }

  // Any files from any field
  @Post('any')
  @UseInterceptors(AnyFilesInterceptor({ storage: memoryStorage() }))
  uploadAny(@UploadedFiles() files: Express.Multer.File[]) { ... }

  // Named fields
  @Post('fields')
  @UseInterceptors(
    FileFieldsInterceptor([{ name: 'avatar' }, { name: 'cover', maxCount: 1 }], {
      storage: memoryStorage(),
    }),
  )
  uploadFields(@UploadedFiles() files: { avatar?: Express.Multer.File[]; cover?: Express.Multer.File[] }) { ... }

  // No files allowed — parses form fields only
  @Post('form')
  @UseInterceptors(NoFilesInterceptor())
  formData(@Body() body: Record<string, string>) { ... }
}

Storage engines

Memory storage (default)

Files are buffered in memory as Buffer objects. This is the default when neither storage nor dest is specified.

import { memoryStorage } from 'nestjs-busboy';

FileInterceptor('file', { storage: memoryStorage() })

Disk storage

Files are written to disk. The destination directory is created automatically.

import { diskStorage } from 'nestjs-busboy';

FileInterceptor('file', {
  storage: diskStorage({
    destination: '/uploads',
    filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`),
  }),
})

Or use the dest shorthand (generates random filenames):

BusboyModule.register({ dest: '/uploads' })

Options

Option	Type	Description
storage	StorageEngine	Custom storage engine. Defaults to MemoryStorage.
dest	string	Destination directory. Uses DiskStorage with random filenames.
fileFilter	FileFilter	Function to control which files are accepted.
limits	BusboyLimits	Limits on incoming data (file size, file count, etc.).
preservePath	boolean	Preserve the full path of the original filename.

Migrating from @nest-lab/fastify-multer

1. Replace @nest-lab/fastify-multer with nestjs-busboy in your dependencies.
2. Replace FastifyMulterModule with BusboyModule in your imports.
3. Replace memoryStorage / diskStorage imports — they now come from nestjs-busboy directly instead of fastify-multer/lib.

-import { FastifyMulterModule } from '@nest-lab/fastify-multer';
-import { memoryStorage } from 'fastify-multer/lib';
+import { BusboyModule, memoryStorage } from 'nestjs-busboy';

-FastifyMulterModule.register({ ... })
+BusboyModule.register({ ... })

All interceptor names and options are identical.