rewriteCssUrls() — astro Function Reference

Architecture documentation for the rewriteCssUrls() function in style.ts from the astro codebase.

Function typescript CoreAstro RenderingEngine called by 1

Entity Profile

CoreAstro→ RenderingEngine→ rewriteCssUrls() — astro Function Reference

Dependency Diagram

graph TD
  94f7ea92_ecd9_fcad_1576_0bd69df25391["rewriteCssUrls()"]
  b49b1fb8_9e6f_4c97_cf66_98d4fd2b7754["style.ts"]
  94f7ea92_ecd9_fcad_1576_0bd69df25391 -->|defined in| b49b1fb8_9e6f_4c97_cf66_98d4fd2b7754
  0160d787_c349_53b5_38f7_e3c1aa80c392["createStylePreprocessor()"]
  0160d787_c349_53b5_38f7_e3c1aa80c392 -->|calls| 94f7ea92_ecd9_fcad_1576_0bd69df25391
  style 94f7ea92_ecd9_fcad_1576_0bd69df25391 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/astro/src/core/compile/style.ts lines 28–79

function rewriteCssUrls(css: string, base: string): string {
	// Only rewrite if base is not the default '/'
	if (!base || base === '/') {
		return css;
	}

	// Normalize base path (remove trailing slash for consistent joining)
	const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base;

	// Safety check: base should start with '/' (already normalized by Astro config)
	if (!normalizedBase.startsWith('/')) {
		return css;
	}

	// Vite's production-tested regex for matching url() in CSS
	// Matches url(...) while handling quotes, unquoted URLs, and edge cases
	// Excludes @import statements via negative lookbehind
	// Matches Vite's cssUrlRE pattern exactly - capturing groups preserved for compatibility
	const cssUrlRE =
		// eslint-disable-next-line regexp/no-unused-capturing-group
		/(?<!@import\s+)(?<=^|[^\w\-\u0080-\uffff])url\((\s*('[^']+'|"[^"]+")\s*|(?:\\.|[^'")\\])+)\)/g;

	return css.replace(cssUrlRE, (match, rawUrl: string) => {
		// Extract URL value, removing quotes if present
		let url = rawUrl.trim();
		let quote = '';

		// Check if URL is quoted (single or double)
		if ((url.startsWith("'") && url.endsWith("'")) || (url.startsWith('"') && url.endsWith('"'))) {
			quote = url[0];
			url = url.slice(1, -1);
		}

		url = url.trim();

		// Only rewrite root-relative URLs (start with / but not //)
		const isRootRelative = url.startsWith('/') && !url.startsWith('//');

		// Skip external URLs and data URIs
		const isExternal =
			url.startsWith('data:') || url.startsWith('http:') || url.startsWith('https:');

		// Skip if already has base path (makes function idempotent)
		const alreadyHasBase = url.startsWith(normalizedBase + '/');

		if (isRootRelative && !isExternal && !alreadyHasBase) {
			return `url(${quote}${normalizedBase}${url}${quote})`;
		}

		return match;
	});
}