feat(media): External Storage Support for Media Uploads

[MrSociety404]

Summary

• Add support for uploading media files to external Object Storage Services (OSS) like Cloudflare R2, AWS S3, or any S3-compatible provider
• Implement configurable upload, list, and delete endpoints for managing external media
• Keep Git repository lean by storing only media URLs instead of binary files
• Provide a complete Cloudflare R2 reference implementation in the playground

Motivation

For projects with large media libraries, committing binary files to Git causes repository bloat and slow clone times. This feature allows teams to offload media storage to cloud providers while maintaining the same intuitive Studio media library experience.

Changes

Module Configuration (src/module/src/module.ts)

• New studio.media configuration option with enabled, endpoint, listEndpoint, deleteEndpoint, maxFileSize, and allowedTypes settings

New Composables

• useOSSUpload - Handles file validation and uploads to configured endpoints
• Enhanced useDraftMedias - Supports both local and OSS media items

Types (src/app/src/types/media.ts)

• MediaItem extended with ossUrl, ossKey, and ossMetadata fields
• OSSUploadResult, OSSUploadError, and OSSUploadResponse types

Reference Implementation (playground/docus/)

• Complete Cloudflare R2 integration example
• Upload, list, and delete endpoints with authentication
• R2 client utility and session verification

Documentation (docs/content/6.medias.md)

• Storage options comparison table
• Configuration guide with all options
• Endpoint implementation patterns
• Step-by-step Cloudflare R2 setup guide

Test plan

• Verify default Git-based media uploads still work
• Enable OSS configuration and test upload to R2
• Test file size and MIME type validation
• Verify media list shows both local and OSS files
• Test delete functionality for OSS media
• Confirm OSS media URLs work in editor preview

[vercel]

@MrSociety404 is attempting to deploy a commit to the Nuxt Team on Vercel.

A member of the Team first needs to authorize it.

[larbish]

Thanks a lot for this pull request @MrSociety404! I'll have a check at it next week 🫡

[MrSociety404]

Thanks a lot for this pull request @MrSociety404! I'll have a check at it next week 🫡

Hey there! Did you have a chance to review my PR? 👀

[MattA-Official]

I was just looking over this as I think it would benefit my team. One consideration I would like to suggest is to integrate Nuxt Blob Storage via NuxtHub as this could massively simplify the configuration process for your suggested S3-compatible providers?

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
content-studio	Error		Feb 26, 2026 0:02am
nuxt.studio	Error		Feb 26, 2026 0:02am

[larbish]

Hey @MrSociety404, one more update:

I've reworked the storage layer to drop the unstorage approach in favor of NuxtHub blob storage. S3 providers are still supported but now Vercel blob is also available.

The detection logic stays simple, we check that @nuxthub/core is installed and blob is enabled.

The docs have been updated to reflect the new setup. Can you give it a try with https://pkg.pr.new/nuxt-content/nuxt-studio@63dc74a and let me know if it works for you?

[larbish]

@MattA-Official I did integrate Nuxt Blob storage. Do you have any project you can try this PR with? 🙏

[MattA-Official]

I'm currently testing it with https://github.com/pups-in-the-park/website/tree/feat/cloudflare-r2-storage but I think I might have broken something in doing so... Upload works - and I can manage it in my R2 Dashboard - but the media page doesn't appear to show anything.

The image searcher shows "No images available"

Additionally, when I have uploaded something I have to review and commit the changes and then alongside the image being added to R2 it is committing it to the repo still. I'm not sure if I've perhaps configured something incorrectly?

https://feat-cloudflare-r2-storage-website.pups-in-the-park.workers.dev/

[larbish]

@MattA-Official To be honest I only tried Cloudflare R2 storage with the s3driver (using env variable) since I'm not deploying on Cloudlfare... Do you feel that you can debug it? Can you also try with the s3 driver to ensure it works?

[MrSociety404]

@MattA-Official, I’m experiencing the same issues with Cloudflare R2 when using the Docus playground. It appears to have been fixed in my last commit. The previous string replacement created a start path of // instead of / only if the prefix was empty.

Could you please confirm that the issues have been resolved?

I should also mention that I’ve tested the issue with environment variables, but I haven’t tested it with the Nuxt Hub configuration for R2.

[larbish]

Thanks @MrSociety404, I did remove this strip just before comiting my last update 🙈

Looks all good now!

Ready to merge 🎉

[larbish]

Additionally, when I have uploaded something I have to review and commit the changes and then alongside the image being added to R2 it is committing it to the repo still. I'm not sure if I've perhaps configured something incorrectly?

This was a bug, I've fixed it also.