Overview

Nhost Storage is a file storage service seamlessly integrated with the GraphQL API and its Permission System. Files are stored on an S3-compatible backend, metadata is managed through GraphQL, and access control is handled by the same Hasura permission system used for the rest of your data. Files are served through a CDN for optimal performance.

How Storage Works

When you upload a file, the Storage service validates the user’s JWT, checks permissions via Hasura, stores the file content in S3, and records metadata in the storage.files table. Downloads follow the same path in reverse — permissions are checked before the file is served. See Architecture for the full request flow.

// Upload a file
const response = await nhost.storage.uploadFiles({
  'bucket-id': 'default',
  'file[]': [file],
})

// Download a file
const { body } = await nhost.storage.getFile(fileId)
const url = URL.createObjectURL(body)

Buckets

Buckets are containers that organize files and group configuration. Each bucket can have its own size limits, cache settings, and pre-signed URL configuration. Every project includes a default bucket; you can create additional buckets for different use cases (e.g., avatars, documents, communities).

Permissions

Permissions follow a Zero Trust model — no role has access by default. You grant access by configuring insert, select, and delete permissions on the storage.files table in Hasura. The same session variables (X-Hasura-User-Id, X-Hasura-Role, custom claims) available in your GraphQL permissions also work for storage.

Image Transformation

Images can be transformed on-the-fly by adding query parameters to file URLs. Resize, change format (WebP, AVIF), adjust quality, and apply blur — all cached at the CDN layer.

// Fetch a 100x100 WebP thumbnail
const { body } = await nhost.storage.getFile(fileId, {
  w: 100,
  h: 100,
  f: 'webp',
})
const url = URL.createObjectURL(body)

Concepts

Architecture

How Storage integrates with Auth, GraphQL, and S3

Buckets

Organize files with configurable containers

Permissions

Control access with Hasura’s permission system

Image Transformation

Resize, convert, and optimize images on-the-fly

Guides

File Operations

Upload, download, replace, and delete files

Pre-signed URLs

Generate temporary secure URLs for file access

Display Images

Fetch authenticated images and render them in the browser

Permissions and Relationships

Set up user files, department files, and GraphQL relationships

Platform

CDN

Global content delivery and caching

Antivirus

Scan uploads with ClamAV integration