1.2.3 • Public • Published


    Role Name Email Slack
    Product Owner Frances Haugen frances@gigster.com [@frances]
    Maintainer Jerome Curlier jerome@gigster.com [@jerome]
    Contributor Samuel Gordalina sam@gigster.com [@sam]


    This module provides file upload for Loopback.

    The module is using the Loopback Storage component. Please therefore review this component documentation to learn about this module.

    The LoopBack storage component makes it easy to upload and download files to cloud storage providers and the local (server) file system.

    • Amazon
    • Azure
    • Google Cloud
    • Openstack
    • Rackspace
    • Local filesytem


      name: loopback-file-upload
        location: 'npm:@gigster/module-loopback-file-upload@1.2.1'
          minSize: 0
          maxSize: 20971520
          storage: filesystem
          containerName: uploads


    Name Status
    containerName the name of the folder or bucket to store the files into.
    minSize Minimum size of the file in bytes.
    maxSize Maximum size of the file in bytes.
    storage Which storage to use for the component, currently filesystem and amazonS3 are supported.

    Uploadable model definition

    A model is uploadable when it has the file-upload.uploadable tag.

    By default, the uploadable model should have the following attributes.

    Name Status
    filename the uniquely generated filename.
    displayName the original file name.
    url the URL location to download the file.
    size the size of the file in bytes.
    mimeType the mime type for the file.
    created the date/time the file was uploaded.

    Note: if you would like to change the list of attributes, you will need to update the uploader mixin generated code. The method storeFile is returning the upload object to be stored for the uploaded file.

    This is an example of a uploadable model.

    name: upload
    public: false
      name: filename
        type: string
      name: displayName
        type: string
      name: url
        type: string
      name: size
        type: number
      name: mimeType
        type: string
      name: created
        type: date
      name: profilePhoto
        type: hasOne
        model: user
        foreignKey: profilePhotoId
      name: userPhotos
        type: hasMany
        model: user
        through: userPhoto
        foreignKey: photoId
      name: productDocument
        type: hasMany
        model: product
        through: productDocument
        foreignKey: documentId
      - file-upload.uploadable


    The module create a POST endpoint for each relation to an uploadable model.

    Endpoint Method Description
    POST /model/relation/upload ( for example /user/profilePhoto/upload) relationUpload Uploads a file

    The following information is returned for each uplodaded file.

        "filename": "ae99c364-0218-4a33-a5e3-3fdb6e07e817.json",
        "displayName": "workspace.json",
        "size": 148841,
        "lastModified": "2017-11-22T20:15:15.376Z",
        "url": "",
        "id": 47

    We can then display the file using the URL provided.

    Sample CURL commands

    curl --request POST \
      --url http://localhost:3000/api/users/1/profilePhoto/upload \
      --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
      --form file=

    Environment variables

    Name Description
    GIG_MAX_UPLOAD_SIZE Maximum size of the file (checked by the storage component)
    AWS_REGION AWS region key when using AWS
    AWS_KEY AWS key when using AWS
    AWS_SECRET_KEY AWS secret key when using AWS


    The loopback-file-upload depends on the loopback-models module. The loopback-models module should be defined before loopback-file-upload in the gig.yaml.

    The following npm packages are used:

    npm version
    loopback-component-storage ^3.3.1



    The Uploader mixin is added to the project. The mixin attaches an upload method to each relation defined in the mixin configuration, handles the file upload to the storage and store the file information in the uploadable model.


    For each relation to a uploadable model, the module contributes the upload endpoint. The endpoint is attached to the model through a mixins configuration in the model json file.

    For example:

        "relations": [

    The module also disable methods related to the uploadble methods.

    For a many relationship, the following methods are disabled:

    • prototype.__create__relation_name
    • prototype.__update__relation_name
    • prototype.__updateById__relation_name
    • prototype.__link__relation_name
    • prototype.__unlink__relation_name

    Otherwise, for a one relationship:

    • prototype.__create__relation_name
    • prototype.__update__relation_name

    where relation_name is the name of the relation.

    For example, for a user model having one profile photo and many photos:

        "disable": [


    The following configuration is added to the Loopback configuration.

      "upload": {
        "containerName": "uploadsBucket",
        "minSize": 0,
        "maxSize": 20971520

    This is based on the module configuration.



    The file are stored under the folder name provided by the configuration in the storage folder. The default folder name is uploads.

    The files are then available through the url


    The file are stored in the bucket provided by the configuration. The default folder name is uploads.

    The files are then then available through the AWS url.


    DEBUG=loopback:file-upload:* yarn start




    npm i @gigster/module-loopback-file-upload

    DownloadsWeekly Downloads






    Unpacked Size

    25.6 kB

    Total Files


    Last publish