You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 29f09f2
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/start/framework/react/guide/cdn-asset-urls.md
+61-12Lines changed: 61 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,15 +9,14 @@ title: CDN Asset URLs
9
9
10
10
When deploying to production, you may want to serve your static assets (JavaScript, CSS) from a CDN. The `transformAssets` option on `createStartHandler` lets you rewrite asset URLs at runtime - for example, prepending a CDN origin that is only known when the server starts.
11
11
12
-
`transformAssetUrls` still works, but it is deprecated and now delegates to `transformAssets` with a development warning.
13
-
14
12
## Why Runtime URL Rewriting?
15
13
16
14
Vite's `base` config is evaluated at build time. If your CDN URL is determined at deploy time (via environment variables, dynamic configuration, etc.), you need a way to rewrite URLs at runtime. `transformAssets` solves this for the URLs that TanStack Start manages in its manifest:
17
15
18
16
-`<link rel="modulepreload">` tags (JS preloads)
19
17
-`<link rel="stylesheet">` tags (CSS)
20
18
- The client entry `<script>` tag
19
+
-`url(...)` and `@import` URLs inside [inlined CSS](./css-styling#css-inlining) when CSS URL templates are enabled
21
20
22
21
## Basic Usage
23
22
@@ -84,7 +83,7 @@ Kinds not listed in the per-kind record receive no `crossOrigin` attribute. Like
84
83
85
84
### Callback
86
85
87
-
For more control, pass a callback that receives `{ kind, url }`and returns a string, or `{ href, crossOrigin? }` (or a `Promise` of either). By default, the transformed manifest is cached after the first request (`cache: true`), so the callback only runs once in production:
86
+
For more control, pass a callback that receives an asset context and returns a string, or `{ href, crossOrigin? }` (or a `Promise` of either). The context is discriminated by `kind`; when `kind === 'css-url'`, it also includes `stylesheetHref`. By default, the transformed manifest is cached after the first request (`cache: true`), so the callback only runs once in production:
88
87
89
88
```tsx
90
89
// src/server.ts
@@ -96,10 +95,10 @@ import { createServerEntry } from '@tanstack/react-start/server-entry'
|`'clientEntry'`| Client entry module URL (used in `import('...')`) |
124
+
|`'css-url'`|`url(...)` or `@import` URL inside inlined CSS |
125
+
126
+
For `kind === 'css-url'`, the context also includes `stylesheetHref`, which is the manifest stylesheet href whose CSS content is being inlined.
127
+
128
+
`crossOrigin` applies to manifest-managed link tags. For the client entry and CSS-internal URLs, returning `{ href }` is equivalent to returning a string.
129
+
130
+
### Inlined CSS URLs
131
+
132
+
When Start's [CSS inlining](./css-styling#css-inlining) is enabled, Start can also run `transformAssets` for URLs inside the inlined CSS content. This covers relative and root-relative `url(...)` and `@import` values, such as fonts and background images.
133
+
134
+
Because Start does not parse CSS at runtime, this requires opting into build-time CSS URL templates:
135
+
136
+
```ts
137
+
tanstackStart({
138
+
server: {
139
+
build: {
140
+
inlineCss: {
141
+
enabled: true,
142
+
transformAssets: true,
143
+
},
144
+
},
145
+
},
146
+
})
147
+
```
148
+
149
+
Passing `inlineCss: true` still inlines route CSS, but it does not emit the template metadata needed for runtime CSS URL transforms.
150
+
151
+
Relative CSS URLs are resolved against the emitted stylesheet href before your transform runs:
Absolute URLs, protocol-relative URLs, data URLs, and hash references inside CSS are left unchanged and are not passed to `transformAssets`. If CSS URL templates were not enabled for the build, URLs inside inlined CSS are left unchanged at runtime.
127
176
128
177
### Object Form (Explicit Cache Control)
129
178
@@ -186,15 +235,15 @@ transformAssets: {
186
235
const region =ctx.request.headers.get('x-region') ||'us'
187
236
const cdnBase =awaitfetchCdnBaseForRegion(region)
188
237
189
-
return ({ kind, url }) => {
190
-
if (kind==='modulepreload') {
238
+
return (asset) => {
239
+
if (asset.kind==='modulepreload') {
191
240
return {
192
-
href: `${cdnBase}${url}`,
241
+
href: `${cdnBase}${asset.url}`,
193
242
crossOrigin: 'anonymous',
194
243
}
195
244
}
196
245
197
-
return { href: `${cdnBase}${url}` }
246
+
return { href: `${cdnBase}${asset.url}` }
198
247
}
199
248
},
200
249
}
@@ -282,7 +331,7 @@ Using an empty string rather than `'./'` is important - both produce relative cl
282
331
283
332
## What This Does Not Cover
284
333
285
-
`transformAssets`only rewrites URLs in the TanStack Start manifest - the tags emitted during SSR for preloading and bootstrapping the application.
334
+
`transformAssets` rewrites URLs in the TanStack Start manifest - the tags emitted during SSR for preloading and bootstrapping the application - and URLs inside CSS that Start inlines into the HTML when CSS URL templates are enabled.
286
335
287
336
It does not rewrite asset URLs imported directly in your components:
0 commit comments