Defining Uploaders

To assist with uploading files in your app, Joystick includes support for defining custom uploader endpoints that can target one or more providers (e.g., your app’s local disk or Amazon S3). Uploaders can:

• Validate uploads based on MIME type and size.
• Customize file destinations and names in storage.
• Hook into before and after upload events for custom behavior (e.g., using imagemagick or ffmpeg).

Example Usage

Defining an Uploader with Local and S3 Providers

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: {
        path: 'uploads',
      },
      s3: {
        region: 'us-east-2',
        access_key_id: joystick?.settings?.private?.aws?.access_key_id,
        secret_access_key: joystick?.settings?.private?.aws?.secret_access_key,
        bucket: 'cheatcode-joystick',
        acl: 'public-read',
      },
    },
  },
});

To keep access_key_id and secret_access_key secure, use references to settings.<env>.json instead of hard-coding them:

{
  "config": { ... },
  "global": {},
  "public": {},
  "private": {
    "aws": {
      "access_key_id": "ABCD...",
      "secret_access_key": "abcd123..."
    }
  }
}

Adding MIME Type Validation

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: { ... },
      s3: { ... },
      mime_types: ['image/png', 'image/jpg', 'image/jpeg', 'image/gif'],
    },
  },
});

Adding File Size Validation

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: { ... },
      s3: { ... },
      max_size_in_megabytes: 50,
    },
  },
});

Customizing File Names

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: { ... },
      s3: { ... },
      file_name: ({ input, file_name }) => {
        return `images/${file_name}`;
      },
    },
  },
});

Using on_before_upload

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: { ... },
      s3: { ... },
      on_before_upload: ({ input, req, uploads }) => {
        // Perform validation or transformations here
      },
    },
  },
});

Using on_after_upload

import joystick from '@joystick.js/node';

joystick.app({
  uploaders: {
    example_uploader: {
      providers: ['local', 's3'],
      local: { ... },
      s3: { ... },
      on_after_upload: ({ input, req, uploads }) => {
        // Post-processing after upload
      },
    },
  },
});

Supported Providers

API

Definition

{
  uploaders: {
    [uploader_name: string]: {
      providers: array[string],
      local: { path: string },
      s3: {
        region: string,
        access_key_id: string,
        secret_access_key: string,
        bucket: string,
        acl: string,
      },
      mime_types: array[string],
      max_size_in_megabytes: integer | function,
      file_name: (options: object) => string,
      on_before_upload: (options: object) => void,
      on_after_upload: (options: object) => void,
    }
  }
}

Parameters

uploader_name object required

An object defining an uploader.

providers array[string] required

An array of provider keys that will handle the upload. Can contain one or both of: local, s3.

local object

Configuration for uploads to the local disk.

path string required

The path relative to your app’s root where files will be stored.

s3 object

Configuration for Amazon S3 uploads.

region string required

The AWS region of your S3 bucket.

access_key_id string required

Your AWS Access Key ID.

secret_access_key string required

Your AWS Secret Access Key.

bucket string required

The name of the S3 bucket where files will be stored.

acl string required

The ACL permissions for uploaded files.

mime_types array[string]

An array of allowed MIME types for uploaded files.

max_size_in_megabytes integer | function

The maximum allowed file size in megabytes, or a function returning it dynamically.

file_name function

A function returning the customized file path/name for the upload.

on_before_upload function

A function run before the upload is sent to providers.

on_after_upload function

A function run after the upload is completed for all providers.