diff --git a/docs/content/3.usage.md b/docs/content/3.usage.md
index a6a4930a..c5057852 100644
--- a/docs/content/3.usage.md
+++ b/docs/content/3.usage.md
@@ -258,6 +258,8 @@ const version = useStrapiVersion()
This composable is a helper to get the full URL for media. Strapi endpoints return media URLs as relative paths (e.g. `/uploads/image.png`) on self-hosted instances, or absolute URLs on Strapi Cloud. This composable handles both cases automatically.
+Relative media paths use `runtimeConfig.public.strapi.url`, including during server-side rendering and static generation, so the URLs are accessible to browsers even when the server uses a different internal Strapi URL.
+
```vue
+
+
+
+
![Strapi media]()
+
+ {{ apiUrl }}
+
+
+
diff --git a/test/fixtures/media/nuxt.config.ts b/test/fixtures/media/nuxt.config.ts
new file mode 100644
index 00000000..e8fdcff3
--- /dev/null
+++ b/test/fixtures/media/nuxt.config.ts
@@ -0,0 +1,18 @@
+import { defineNuxtConfig } from 'nuxt/config'
+import strapi from '../../../src/module'
+
+export default defineNuxtConfig({
+ modules: [strapi],
+ pages: false,
+ devtools: { enabled: false },
+ runtimeConfig: {
+ strapi: { url: 'http://localhost:1337', token: '' },
+ public: {
+ strapi: { url: 'https://media.example.com', token: '' }
+ }
+ },
+ compatibilityDate: '2026-05-06',
+ nitro: {
+ prerender: { routes: ['/prerender'], crawlLinks: false }
+ }
+})
diff --git a/test/unit/useStrapiMedia.test.ts b/test/unit/useStrapiMedia.test.ts
index 73658d3b..7107d9c3 100644
--- a/test/unit/useStrapiMedia.test.ts
+++ b/test/unit/useStrapiMedia.test.ts
@@ -3,11 +3,14 @@ import { describe, expect, it, vi } from 'vitest'
import { useStrapiMedia } from '../../src/runtime/composables/useStrapiMedia'
const mockConfig = {
- strapi: { url: 'http://localhost:1337', prefix: '/api', version: 'v5' }
+ strapi: { url: 'http://localhost:1337', prefix: '/api', version: 'v5' },
+ public: {
+ strapi: { url: 'https://media.example.com', prefix: '/api', version: 'v5' }
+ }
}
vi.mock('#imports', () => ({
- useRuntimeConfig: () => ({ public: mockConfig })
+ useRuntimeConfig: () => mockConfig
}))
describe('useStrapiMedia', () => {
@@ -26,13 +29,13 @@ describe('useStrapiMedia', () => {
.toBe('https://domain.media.strapiapp.com/uploads/image.jpg')
})
- it('joins relative paths with strapi URL', () => {
+ it('joins relative paths with the public Strapi URL', () => {
expect(useStrapiMedia('/uploads/image.jpg'))
- .toBe('http://localhost:1337/uploads/image.jpg')
+ .toBe('https://media.example.com/uploads/image.jpg')
})
it('joins paths without leading slash', () => {
expect(useStrapiMedia('uploads/image.jpg'))
- .toBe('http://localhost:1337/uploads/image.jpg')
+ .toBe('https://media.example.com/uploads/image.jpg')
})
})