Storage

Nitric provides storage support for securely storing and retrieving large files in the cloud.

Quick Start

Here's a minimal example to get you started:

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read', 'write')

// Use resources inside functions
async function handleProfileImage() {
  // Upload a file
  await profiles.file('profile.png').write('image data')

  // Download a file
  const image = await profiles.file('profile.png').read()
}

Core Concepts

Buckets

Buckets are isolated repositories for files. Each bucket in your application needs a unique name and specific permissions for reading, writing, and deleting files.

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read', 'write', 'delete')

File References

You can get a reference to a file in a bucket using the file() method. This returns a File reference that you can use to perform operations on the file.

No network calls are made when you get a file reference using file()

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read')

// Use resources inside functions
async function getProfilePicture() {
  const profilePicture = profiles.file('users/bruce-wayne/profile.png')
  return profilePicture
}

Features

Reading Files

Read file contents using the read() method:

If a file doesn't exist when read() is called, a NOT_FOUND error will be thrown.

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read')

// Use resources inside functions
async function readProfileImage() {
  const image = await profiles.file('profile.png').read()
  return image
}

Writing Files

Write file contents using the write() method. If the file doesn't exist, it will be created. If it does exist, it will be overwritten.

Written data cannot exceed 4MB. For larger files, use signed URLs.

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('write')

// Use resources inside functions
async function writeProfileImage() {
  await profiles.file('profile.png').write('image data')
}

Deleting Files

Delete files using the delete() method:

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('delete')

// Use resources inside functions
async function deleteProfileImage() {
  await profiles.file('profile.png').delete()
}

Listing Files

List all files in a bucket using the files() method:

A network call is made when you list files using files()

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read')

// Use resources inside functions
async function listProfileImages() {
  const files = await profiles.files()
  files.forEach((file) => {
    console.log(file.name)
  })
}

Signed URLs

Generate temporary URLs for downloading or uploading files. These URLs include authentication information and are useful for sharing temporary links.

Anyone with the signed URL can access or modify the file. Only share URLs with trusted users.

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles').allow('read', 'write')

// Use resources inside functions
async function getSignedUrls() {
  const downloadUrl = await profiles.file('profile.png').getDownloadUrl({
    expiry: 3600, // Expires in 1 hour
  })

  const uploadUrl = await profiles.file('profile.png').getUploadUrl({
    expiry: 3600, // Expires in 1 hour
  })

  return { downloadUrl, uploadUrl }
}

Bucket Notifications

Subscribe to changes in your bucket's files. You can filter notifications by file prefix and event type (write/delete).

Writing/Deleting to a bucket from within a bucket notification will trigger the same notification again, potentially causing an infinite loop.

import { bucket } from '@nitric/sdk'

// Declare resources at the module level
const profiles = bucket('profiles')

// Use resources inside functions
profiles.on('write', '/users/images', (ctx) => {
  console.log(`New profile image for ${ctx.req.key} was created`)
})

Cloud Service Mapping

Each cloud provider comes with a set of default services used when deploying resources. You can find the default services for each cloud provider below.