You are viewing the legacy version of AdonisJS. Visit https://adonisjs.com for newer docs. This version will receive security patches until the end of 2021.

File Storage

AdonisJs has a dedicated Drive Provider built on top of Flydrive to interact with local and remote file systems like Amazon S3.

In this guide, we learn how to set up and use the Drive Provider.

Setup

As the Drive Provider is not installed by default, we need to pull it from npm:

> adonis install @adonisjs/drive

Next, we need to register the provider inside the start/app.js file:

start/app.js
const providers = [
  '@adonisjs/drive/providers/DriveProvider'
]
Driver configuration is saved inside the config/drive.js file, which is created by the adonis install command when installing the Drive Provider.

Available Drivers

The default drivers shipped with the Drive Provider are:

  1. Amazon S3 (s3), which requires the aws-sdk package

  2. DigitalOcean Spaces (spaces), which requires the aws-sdk package

  3. Local file system (local)

Basic Example

Here’s a basic example of how to interact with the local disk via adonis repl:

Drive dlcc3v

Drive API

While common operations like reading and writing remain the same across drivers, the API of a drive is mainly based upon the driver you’re using to interact with that drive’s file system.

exists(relativePath)

Find if a file/directory exists or not:

const exists = await Drive.exists('unicorn.jpg')

get(relativePath, encoding = utf-8)

Get file contents as a buffer or string:

const unicorn = await Drive.get('unicorn.jpg')

getStream(relativePath)

Get file as a stream:

Drive.getStream('hello.txt')

put(relativePath, content, options = {})

Create a new file with given contents (creates any missing directories):

await Drive.put('hello.txt', Buffer.from('Hello world!'))

prepend(relativePath, content, options = {})

Prepend content to a file (creates a new file if path doesn’t exist):

await Drive.prepend('hello.txt', Buffer.from('Prepended!'))
The prepend method only works with the local driver.

append(relativePath, content, options = {})

Append content to a file (creates a new file if path doesn’t exist):

await Drive.append('hello.txt', Buffer.from('Appended!'))
The append method only works with the local driver.

delete(relativePath)

Remove existing file:

await Drive.delete('hello.txt')

move(src, dest, options = {})

Move file from one directory to another:

await Drive.move('hello.txt', 'hi.txt')

copy(src, dest, options = {})

Copy file from one directory to another:

await Drive.copy('hi.txt', 'hello.txt')

S3/Spaces API

The following methods work for the s3 and spaces drivers only.

getObject(location, params)

Get S3 object for a given file (for params info, see S3 params):

await Drive.disk('s3').getObject('unicorn.jpg')

getUrl(location, [bucket])

Get url for a given file (accepts optional alternative bucket param):

const url = Drive.disk('s3').getUrl('unicorn.jpg')

getSignedUrl(location, expiry = 900, params)

Get signed url for a given file (expiry set to 15mins by default):

const url = await Drive.disk('s3').getSignedUrl('unicorn.jpg')