https://github.com/peterkyle01/storage-supabase
Supabase Storage adapter for Payload CMS 3.0.
https://github.com/peterkyle01/storage-supabase
Last synced: about 1 month ago
JSON representation
Supabase Storage adapter for Payload CMS 3.0.
- Host: GitHub
- URL: https://github.com/peterkyle01/storage-supabase
- Owner: peterkyle01
- License: mit
- Created: 2026-04-27T19:51:47.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T09:03:19.000Z (2 months ago)
- Last Synced: 2026-04-28T09:33:24.353Z (2 months ago)
- Language: TypeScript
- Size: 200 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# storage-supabase
Supabase Storage adapter for Payload CMS 3.0+.
This adapter integrates Supabase Storage with Payload's upload system. It is designed to be lightweight, using native `fetch` instead of the AWS SDK, and supports Supabase-specific features like direct redirects and image transformations.
## Installation
```sh
npm install storage-supabase
```
## Setup
### 1. Get Your Supabase Credentials
Go to your Supabase Dashboard → **Settings → API** and copy:
- **Project URL**: `https://your-project.supabase.co`
- **Secret Key**: `sb_secret_...` (from the API Keys section)
> ⚠️ Use the new **Secret Key** format (`sb_secret_...`), not the legacy `service_role` key.
### 2. Set Environment Variables
```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_BUCKET=your-bucket-name
SUPABASE_SECRET_KEY=sb_secret_your_secret_key_here
```
### 3. Configure the Plugin
```ts
import { storageSupabase } from 'storage-supabase'
import { buildConfig } from 'payload'
export default buildConfig({
plugins: [
storageSupabase({
bucket: process.env.SUPABASE_BUCKET,
supabaseUrl: process.env.SUPABASE_URL,
supabaseKey: process.env.SUPABASE_SECRET_KEY,
collections: {
media: true,
},
// Optional configurations
disableProxy: true,
imageOptimization: {
quality: 80,
format: 'webp',
}
}),
],
})
```
## Configuration
| Option | Type | Description |
| :--- | :--- | :--- |
| `bucket` | `string` | **Required**. Supabase bucket name. |
| `supabaseUrl` | `string` | **Required**. Supabase project URL (e.g., `https://xyz.supabase.co`) or bucket endpoint (e.g., `https://xyz.storage.supabase.co/storage/v1/s3`). Both formats are supported. |
| `supabaseKey` | `string` | **Required**. Secret API Key in the format `sb_secret_...`. Get this from your Supabase Dashboard → Settings → API → Secret Key. |
| `collections` | `object` | **Required**. Collection slugs to enable the adapter for (e.g., `{ media: true }`). |
| `enabled` | `boolean` | Enable/disable the plugin. Default: `true`. |
| `public` | `boolean` | Set to `true` for public buckets, `false` for private buckets. Default: `true`. |
| `disableProxy` | `boolean` | Redirect directly to Supabase CDN instead of proxying through the server. Default: `true`. |
| `imageOptimization` | `object` | Options for Supabase image transformations: `quality` (number), `format` ('avif', 'webp', 'origin'), `resize` ('contain', 'cover', 'fill'). |
## API Key Format
This adapter requires the **new Supabase API key format**:
- ✅ **Use**: `sb_secret_...` keys (new format)
- ❌ **Don't use**: Legacy `service_role` JWT keys
If you only see JWT-format keys in your Supabase Dashboard, your project may need to be upgraded. Contact Supabase support or create a new project to access the new key system.
## Troubleshooting
### "Invalid Supabase API key"
Make sure you're using a key starting with `sb_secret_`, not `sb_publishable_` or legacy JWT format.
### "Unsupported authorization type"
Verify you're using the correct `sb_secret_...` key and that your bucket name is correct.
### Uploads not working with private buckets
For private buckets, ensure `public: false` is set in the configuration, and that your Supabase bucket has appropriate access policies.
## License
MIT