# Upload files

Ts.ED supports now the uploading files by default. We use Multer (opens new window) module to handle multipart/form-data from request.

TIP

Originally, multer is provided by Express.js, but Ts.ED implements a multer wrapper to support Koa.js platform based on the official @koa/multer (opens new window) module.

# Configuration

By default, the directory used is ${projetRoot}/uploads. You can configure another directory on your Server settings.

    # Options

    • dest (string): The destination directory for the uploaded files.
    • storage (StoreEngine): The storage engine to use for uploaded files.
    • limits (Object): An object specifying the size limits of the following optional properties. This object is passed to busboy directly, and the details of properties can be found on https://github.com/mscdex/busboy (opens new window).
      • fieldNameSize (number): Max field name size (Default: 100 bytes).
      • fieldSize (number): Max field value size (Default: 1MB).
      • fields (number): Max number of non- file fields (Default: Infinity).
      • fileSize (number): For multipart forms, the max file size (in bytes)(Default: Infinity).
      • files (number): For multipart forms, the max number of file fields (Default: Infinity).
      • parts (number): For multipart forms, the max number of parts (fields + files)(Default: Infinity).
      • headerPairs (number): For multipart forms, the max number of header key => value pairs to parse Default: 2000(same as node's http).
    • preservePath (boolean): Keep the full path of files instead of just the base name (Default: false).
    • fileFilter (Function): Optional function to control which files are uploaded. This is called for every file that is processed.

    # Usage

    # Single file

    A single file can be injected to your endpoint by using the MultipartFile decorator like this:

    import {MulterOptions, MultipartFile, PlatformMulterFile} from "@tsed/common";
    import {Post} from "@tsed/schema";
    import {Controller} from "@tsed/di";
    
    @Controller("/")
    class MyCtrl {
      @Post("/file")
      private uploadFile1(@MultipartFile("file") file: PlatformMulterFile) {}
    
      @Post("/file")
      @MulterOptions({dest: "/other-dir"})
      private uploadFile2(@MultipartFile("file") file: PlatformMulterFile) {}
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    TIP

    Many frontend code examples are available on the web and some of them don't work as expected. So, to help you, here is a short vanilla Javascript code example:

    export async function loadFile(file) {
      const formData = new FormData();
      formData.append("file", file);
    
      await fetch(`/rest/upload`, {
        method: "POST",
        headers: {
          // don't set Content-Type: multipart/form-data. It's set automatically by fetch (same things with axios)
        },
        body: formData
      });
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

    # Multiple files

    For multiple files, just use PlatformMulterFile[] annotation type. Ts.ED will understand that you want to inject a list of files even if your consumer only sends you one:

    import {MultipartFile, PlatformMulterFile} from "@tsed/common";
    import {Post} from "@tsed/schema";
    import {Controller} from "@tsed/di";
    
    @Controller("/")
    class MyCtrl {
      @Post("/files")
      private uploadFile(@MultipartFile("files", 4) files: PlatformMulterFile[]) {
        // multiple files with 4 as limits
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

    WARNING

    Swagger spec (v2.0) doesn't support multiple files. Enable OAS 3 to support multipart files in swagger-ui.

    Last Updated: 4/6/2022, 10:49:26 AM

    Other topics