upstream-hocuspocus/packages/extension-s3

@hocuspocus/extension-s3

A S3-compatible persistence driver for Hocuspocus. Stores Y.js documents in Amazon S3 or S3-compatible storage (MinIO, DigitalOcean Spaces, Cloudflare R2, Backblaze B2, etc.).

Installation

npm install @hocuspocus/extension-s3

Quick Start

Basic AWS S3 Configuration

import { Server } from '@hocuspocus/server'
import { S3 } from '@hocuspocus/extension-s3'

const server = new Server({
  extensions: [
    new S3({
      bucket: 'my-documents-bucket',
      region: 'us-east-1',
      credentials: {
        accessKeyId: 'your-access-key',
        secretAccessKey: 'your-secret-key'
      }
    }),
  ],
})

server.listen()

MinIO Configuration

For local development with MinIO, ensure you set forcePathStyle: true:

const server = new Server({
  extensions: [
    new S3({
      bucket: 'hocuspocus-documents',
      endpoint: 'http://localhost:9000',
      forcePathStyle: true,
      credentials: {
        accessKeyId: 'minioadmin',
        secretAccessKey: 'minioadmin'
      }
    }),
  ],
})

Configuration Options

• bucket (required): S3 bucket name where documents will be stored
• region: AWS region (default: 'us-east-1')
• prefix: Key prefix for documents (default: 'hocuspocus-documents/')
• credentials: AWS credentials object with accessKeyId and secretAccessKey
• endpoint: S3 endpoint URL (for S3-compatible services)
• forcePathStyle: Use path-style URLs (required for MinIO, default: false)
• s3Client: Custom S3Client instance

Document Storage

Documents are stored as binary files in S3 with the naming convention: {prefix}{documentName}.bin

Scaling with Redis

For horizontal scaling, combine S3 with the Redis extension. Redis handles real-time synchronization while S3 provides persistent storage.

import { Server } from '@hocuspocus/server'
import { Logger } from '@hocuspocus/extension-logger'
import { Redis } from '@hocuspocus/extension-redis'
import { S3 } from '@hocuspocus/extension-s3'

// Server 1
const server1 = new Server({
  name: "server-1",
  port: 8001,
  extensions: [
    new Logger(),
    new Redis({
      host: "127.0.0.1",
      port: 6379,
    }),
    new S3({
      bucket: 'hocuspocus-documents',
      endpoint: 'http://localhost:9000', // MinIO
      forcePathStyle: true,
      credentials: {
        accessKeyId: 'minioadmin',
        secretAccessKey: 'minioadmin'
      }
    }),
  ],
})

// Server 2 - same configuration with different name/port
const server2 = new Server({
  name: "server-2", 
  port: 8002,
  extensions: [/* same extensions */],
})

server1.listen()
server2.listen()

CLI Usage

You can also use the S3 extension with the Hocuspocus CLI:

# Basic usage
hocuspocus --s3 --s3-bucket my-documents

# MinIO setup (forcePathStyle automatically enabled)
hocuspocus --s3 --s3-bucket hocuspocus-documents --s3-endpoint http://localhost:9000

Development

Quick Start

For local development with MinIO (S3-compatible storage):

# Set up development environment
npm run dev:setup

# Test S3 configuration  
npm run dev:test-s3

# Run S3 playground examples
npm run playground:s3

Complete Documentation

For detailed documentation, examples, best practices, and troubleshooting, see: 📚 S3 Extension Documentation

IAM Permissions

Your AWS credentials or IAM role needs the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:HeadObject"],
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    },
    {
      "Effect": "Allow", 
      "Action": ["s3:HeadBucket"],
      "Resource": "arn:aws:s3:::your-bucket-name"
    }
  ]
}