Storage and assets

A reliable path from R2 bucket to asset preview.

Connect a workspace to Cloudflare R2, deliver files through the right URL, and reuse assets from media fields without exposing storage credentials.

Open storage settings

Two URLs, two jobs

Jade keeps object storage credentials and browser delivery separate. This is the most important part of the setup.

Private endpoint

endpoint_url is the S3-compatible endpoint used by the backend for signed uploads and deletes. For a default R2 bucket it is https://<ACCOUNT_ID>.r2.cloudflarestorage.com.

Public delivery URL

asset_base_url is the browser-facing base URL returned with assets and used by previews. Use an R2 custom domain in production, not the S3 endpoint.

Credentials stay server-side

Jade stores the R2 access key and secret in workspace storage settings. The secret is never returned by the settings API and must never be placed in a browser bundle.

Set up Cloudflare R2

Create a bucket, create a scoped token, then choose the correct public delivery option.

Create a bucket

Create an R2 bucket in the Cloudflare dashboard or with Wrangler. Buckets are private by default.

Wrangler

npx wrangler login
npx wrangler r2 bucket create jade-assets-production

Create an Object Read & Write token

In R2 → Overview → Account Details → API Tokens, create an account or user token with Object Read & Write permission scoped to this bucket. Copy the access key ID and secret access key when they are shown.

Choose public delivery

Connect a custom domain under the bucket Settings → Custom Domains for production. Enable Public Development URL only when testing with the rate-limited managed r2.dev URL.

Create R2 bucketsCloudflare docs ↗R2 authentication and token scopesCloudflare docs ↗Public buckets and custom domainsCloudflare docs ↗

Do not use r2.dev for production traffic

The managed r2.dev endpoint is rate-limited and does not provide the production controls available behind a custom domain, including WAF rules, Cloudflare Access, Bot Management, and custom caching. Do not create a CNAME pointing at an r2.devhostname.

Configure Jade

Workspace owners and admins enter the storage connection once; all projects in the workspace can then use the asset library.

Settings → Storage

Storage provider: Cloudflare R2
Bucket name: jade-assets-production
Endpoint URL: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
Public asset base URL: https://cdn.example.com
Region: auto
Cloudflare account ID: <ACCOUNT_ID>
Access key ID: <R2_ACCESS_KEY_ID>
Secret access key: <R2_SECRET_ACCESS_KEY>

Use the right values

Region should be auto for a default R2 bucket. If the bucket uses a jurisdiction, use its jurisdiction- specific S3 endpoint. Set the Public asset base URL to the active custom domain or temporary r2.dev URL without confusing it with the private endpoint.

Use the asset library

The asset page and document editor use the same project-scoped library.

Dedicated page

Select a project and open /app/assets to upload, search, preview, open, copy the public link, or delete files. Image previews use contained rendering and can be opened in a larger modal.

Media fields

In a document editor, choose Select from asset libraryto search existing project assets or upload a new one. Selected images are previewed in the editor and the asset object is stored in document data.

Authenticated asset routes

GET    /api/projects/{projectId}/assets?search=hero
POST   /api/projects/{projectId}/assets?filename=hero.png
DELETE /api/assets/{assetId}

API-key management routes

GET    /api/management/v1/projects/{projectId}/assets?search=hero
POST   /api/management/v1/projects/{projectId}/assets?filename=hero.png
DELETE /api/management/v1/assets/{assetId}

Role requirements

Members can list project assets. Editors can upload and delete them. Workspace owners and admins can read or update storage settings. These app-session routes remain available to the Jade UI. Trusted external integrations use the management routes with assets:reador assets:write API-key scopes.

Production checklist

Use separate environments and rotate credentials when they are exposed.

Use separate R2 buckets and tokens for staging and production.

Scope Object Read & Write tokens to the Jade bucket whenever possible.

Use a custom domain for production asset delivery.

Keep endpoint credentials in Jade workspace settings, never in frontend code.

Verify a small upload, image preview, Open action, Copy link action, and media-field selection after setup.

Rotate the R2 token and update Jade if the secret is exposed.

Current limitations

The shipped library does not yet include private asset delivery with signed URLs, asset dimensions or checksums, reference-aware deletion, soft deletion/recovery, or direct-to-R2 presigned browser uploads.