@uniqueweb/s3-upload

Nuxt 4 module that automatically uploads your static build assets to S3-compatible storage (Cloudflare R2, AWS S3, MinIO, …) after nuxt build.

• ✨  Release Notes

Features

• Uploads built assets to any S3-compatible bucket via the nitro:build:public-assets hook
• Output path and S3 key prefix are derived automatically from nitro.output.publicDir and app.buildAssetsDir — no path config needed
• Skips unchanged files via ETag / MD5 checksum (equivalent to rclone --checksum)
• Concurrent uploads (16 parallel requests)
• Correct Cache-Control headers — immutable for hashed assets, no-store for latest.json
• Zero runtime overhead — build-time only

Setup

npm install @uniqueweb/s3-upload

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@uniqueweb/s3-upload'],

  s3Upload: {
    s3: {
      bucket: 'my-bucket',
      region: 'auto',
      endpoint: 'https://<accountid>.r2.cloudflarestorage.com',
      accessKey: process.env.S3_ACCESS_KEY,
      secretKey: process.env.S3_SECRET_KEY,
    },
  },
})

Configuration

| Option | Type | Required | Description | |------------------|-----------|----------|------------------------------------------------| | bucket | string | yes | S3 bucket name | | region | string | yes | AWS region or auto for Cloudflare R2 | | endpoint | string | yes | S3-compatible endpoint URL | | accessKey | string | yes | Access key ID | | secretKey | string | yes | Secret access key | | forcePathStyle | boolean | no | Use path-style URLs (required for MinIO, etc.) |

If any required field is missing the module logs a warning and skips the upload — the build itself is never aborted.

The upload directory and S3 key prefix are resolved automatically from your Nuxt config.

Environment variables

Store credentials in .env and never commit them:

S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Release new version
npm run release

License

MIT