Skip to content

Commit 29f09f2

Browse files
feat(start): add inline CSS runtime controls and asset URL templates
1 parent b1c061a commit 29f09f2

36 files changed

Lines changed: 1196 additions & 389 deletions
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@tanstack/router-core': patch
3+
'@tanstack/start-plugin-core': patch
4+
'@tanstack/start-server-core': patch
5+
---
6+
7+
Add runtime-configurable inline CSS and opt-in CSS URL templates for transformAssets.

‎docs/start/config.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,10 @@
145145
"label": "CDN Asset URLs",
146146
"to": "framework/react/guide/cdn-asset-urls"
147147
},
148+
{
149+
"label": "CSS Styling",
150+
"to": "framework/react/guide/css-styling"
151+
},
148152
{
149153
"label": "Client Entry Point",
150154
"to": "framework/react/guide/client-entry-point"
@@ -262,6 +266,10 @@
262266
"label": "Early Hints",
263267
"to": "framework/solid/guide/early-hints"
264268
},
269+
{
270+
"label": "CSS Styling",
271+
"to": "framework/solid/guide/css-styling"
272+
},
265273
{
266274
"label": "Client Entry Point",
267275
"to": "framework/solid/guide/client-entry-point"

‎docs/start/framework/react/guide/cdn-asset-urls.md‎

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,14 @@ title: CDN Asset URLs
99
1010
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.
1111

12-
`transformAssetUrls` still works, but it is deprecated and now delegates to `transformAssets` with a development warning.
13-
1412
## Why Runtime URL Rewriting?
1513

1614
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:
1715

1816
- `<link rel="modulepreload">` tags (JS preloads)
1917
- `<link rel="stylesheet">` tags (CSS)
2018
- The client entry `<script>` tag
19+
- `url(...)` and `@import` URLs inside [inlined CSS](./css-styling#css-inlining) when CSS URL templates are enabled
2120

2221
## Basic Usage
2322

@@ -84,7 +83,7 @@ Kinds not listed in the per-kind record receive no `crossOrigin` attribute. Like
8483

8584
### Callback
8685

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:
8887

8988
```tsx
9089
// src/server.ts
@@ -96,10 +95,10 @@ import { createServerEntry } from '@tanstack/react-start/server-entry'
9695

9796
const handler = createStartHandler({
9897
handler: defaultStreamHandler,
99-
transformAssets: ({ kind, url }) => {
100-
const href = `https://cdn.example.com${url}`
98+
transformAssets: (asset) => {
99+
const href = `https://cdn.example.com${asset.url}`
101100

102-
if (kind === 'modulepreload') {
101+
if (asset.kind === 'modulepreload') {
103102
return {
104103
href,
105104
crossOrigin: 'anonymous',
@@ -122,8 +121,58 @@ The `kind` parameter tells you what kind of asset URL is being transformed:
122121
| `'modulepreload'` | JS module preload URL (`<link rel="modulepreload">`) |
123122
| `'stylesheet'` | CSS stylesheet URL (`<link rel="stylesheet">`) |
124123
| `'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:
152+
153+
```css
154+
/* emitted stylesheet href: /assets/dashboard.css */
155+
.card {
156+
background-image: url('./dot.svg');
157+
}
158+
```
125159

126-
`crossOrigin` applies to manifest-managed link tags. For the client entry, returning `{ href }` is equivalent to returning a string.
160+
Your callback receives `/assets/dot.svg`:
161+
162+
```tsx
163+
const handler = createStartHandler({
164+
handler: defaultStreamHandler,
165+
transformAssets: (asset) => {
166+
if (asset.kind === 'css-url') {
167+
return `https://cdn.example.com${asset.url}`
168+
}
169+
170+
return `https://cdn.example.com${asset.url}`
171+
},
172+
})
173+
```
174+
175+
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.
127176

128177
### Object Form (Explicit Cache Control)
129178

@@ -186,15 +235,15 @@ transformAssets: {
186235
const region = ctx.request.headers.get('x-region') || 'us'
187236
const cdnBase = await fetchCdnBaseForRegion(region)
188237

189-
return ({ kind, url }) => {
190-
if (kind === 'modulepreload') {
238+
return (asset) => {
239+
if (asset.kind === 'modulepreload') {
191240
return {
192-
href: `${cdnBase}${url}`,
241+
href: `${cdnBase}${asset.url}`,
193242
crossOrigin: 'anonymous',
194243
}
195244
}
196245

197-
return { href: `${cdnBase}${url}` }
246+
return { href: `${cdnBase}${asset.url}` }
198247
}
199248
},
200249
}
@@ -282,7 +331,7 @@ Using an empty string rather than `'./'` is important - both produce relative cl
282331
283332
## What This Does Not Cover
284333

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.
286335

287336
It does not rewrite asset URLs imported directly in your components:
288337

0 commit comments

Comments
 (0)