Module

@admin-bro/upload

AdminBro feature allowing you to upload files to a given resource.

Installation

To install the upload feature run:

yarn add @admin-bro/upload

Usage

As any feature you have to pass it to the resource in AdminBroOptions#resources property:

const AdminBro = require('admin-bro')
const AdminBroExpress = require('@admin-bro/express')

// part where you load adapter and models
const User = require('./user')

const options = {
  resources: [{
    resource: User,
    options: {
      listProperties: ['fileUrl', 'mimeType'],
    },
    features: [uploadFeature({
      provider: { aws: { region, bucket, secretAccessKey ... } },
      properties: {
        key: 'fileUrl' // to this db field feature will safe S3 key
        mimeType: 'mimeType' // this property is important because allows to have previews
      },
      validation: {
        mimeTypes: 'application/pdf'
      }
    })]
  }]
}

const adminBro = new AdminBro(options)
// and the rest of your app

Previews

Feature support previews for both audio and images. In order to make it work you have to have mimeType property mapped in the options.

Here we define that mime type will be save under a property mimeType:

const options = {
  resources: [{
    resource: User,
    options: { properties: { mimeType: { n} }},
    features: [uploadFeature({
      provider: {},
      properties: {
        key: 'fileUrl'
        mimeType: 'mimeType'
      },
    })]
  }]
}

Providers

Right now plugin supports only AWS S3 as a file hosting. New providers will come soon.

AWS setup

Make sure you have AWS-SDK installed

yarn add aws-sdk

In order to upload files to AWS S3, you have to

Then, fill all these data in AWSOptions and you are ready to go.

By default upload plugin generates urls valid for 24h, if you want them to be always public (public-acl), you need to create a public bucket. Then set expires to 0.

Local Storage setup

Local storage will save files to the local folder.

There are 2 things you have to do before using this Provider.

1. create the folder (bucket) for the files (i.e. public)

cd your-app
mkdir public

2. tell your http framework to host this folder

This is an example for the express server

app.use('/uploads', express.static('uploads'));

Next you have to add @admin-bro/upload to given resource:

* const options = {
  resources: [{
    resource: User,
    features: [uploadFeature({
      provider: { local: { bucket: 'public' } },
    })]
  }]
}

Custom Provider

Plugin allows you also to pass your own provider. In such case you have to pass to the provider option an instance of the class extended from BaseProvider.

const { BaseProvider } = require('@admin-bro/upload')

class MyProvider extends BaseProvider {
  constructor() {
     // it requires bucket as a parameter to properly pass it to other methods
     super('public')
  }
  // your implementation goes here
}

const provider = new MyProvider()

const options = {
  resources: [{
    resource: User,
    features: [uploadFeature({ provider })]
  }]
}

Storing data

This feature require just the one field in the database to store the path (S3 key) of the uploaded file.

But it also can store more data like bucket, 'mimeType', 'size' etc. For the list of all available properties take a look at UploadOptions

Validation

The feature can validate both:

  • maximum size of the file
  • available mime types

Take a look at UploadOptions here as well.

Classes

BaseProvider

See Details

Type Definitions

object

# AWSOptions

AWS Credentials which can be set for S3 file upload. If not given 'aws-sdk' will try to fetch them from environmental variables.

Properties:
Name Type Attributes Description
accessKeyId string <optional>

AWS IAM accessKeyId. By default its value is taken from AWS_ACCESS_KEY_ID env variable

secretAccessKey string <optional>

AWS IAM secretAccessKey. By default its value is taken from AWS_SECRET_ACCESS_KEY env variable

region string

AWS region where your bucket was created.

bucket string

S3 Bucket where files will be stored

expires number | null <optional>

indicates how long links should be available after page load (in minutes)., Default to 24h. If set to 0 or null adapter will mark uploaded files as PUBLIC ACL.

View Source admin-bro-upload/src/features/upload-file/providers/aws-adapter.ts, line 54

object

# AWSOptions

AWS Credentials which can be set for S3 file upload. If not given 'aws-sdk' will try to fetch them from environmental variables.

Properties:
Name Type Attributes Description
accessKeyId string <optional>

AWS IAM accessKeyId. By default its value is taken from AWS_ACCESS_KEY_ID env variable

secretAccessKey string <optional>

AWS IAM secretAccessKey. By default its value is taken from AWS_SECRET_ACCESS_KEY env variable

region string

AWS region where your bucket was created.

bucket string

S3 Bucket where files will be stored

expires number <optional>

indicates how long links should be available after page load (in minutes)., Default to 24h. If set to 0 adapter will mark uploaded files as PUBLIC ACL.

View Source admin-bro-upload/src/features/upload-file/providers/aws-provider.ts, line 51

object

# LocalUploadOptions

Options required by the LocalAdapter

Properties:
Name Type Description
bucket string

Path where files will be stored. For example: path.join(__dirname, '../public')

View Source admin-bro-upload/src/features/upload-file/providers/local-provider.ts, line 30

object

# UploadOptions

Configuration options for @admin-bro/upload feature

Properties:
Name Type Attributes Description
provider object | BaseProvider

Options for the provider

aws AWSOptions <optional>

AWS Credentials

local LocalUploadOptions <optional>

Storage on the local drive

properties object
key string

Property under which file key (path) will be stored

file string <optional>

Virtual property where uploaded file will be passed to from, frontend to the backend in the request payload., Default to file

filePath string <optional>

Virtual property where path for uploaded file will be, generated and accessible on the frontend., Default to filePath

bucket string <optional>

Property under which file bucket (folder) will be stored

mimeType string <optional>

Property under which file mime type will be stored., When you give this system will show a correct icon by the, uploaded file

size string <optional>

Property under which file size will be stored

filename string <optional>

Property under which file name will be stored

validation object <optional>

Validation rules

mimeTypes Array.<MimeType> <optional>

Available mime types

maxSize number <optional>

Maximum size in bytes

View Source admin-bro-upload/src/features/upload-file/upload-options.type.ts, line 7