Build under symbol/junction-linked directories will cause CSS missing

[Chaoses-Ib]

Astro Info

Astro                    v7.0.6
Vite                     v8.1.3
Node                     v26.4.0
System                   Windows (x64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

When npm run build under a symbol/junction link of a Astro project, inline CSS and CSS files, together with CSS file links, will be missing, at least on Windows.

Reproduce PowerShell script:

npm create astro@latest -- --template portfolio
# Name the project 'test'

cd test
npm run build
mv dist dist-baseline

cd ..
# Junction, symlink works too but requires sudo
cmd /c mklink /J linked test
cd linked
npm run build

BaseLayout.*.css is missing:

Inline CSS and CSS file link is missing:

What's the expected result?

CSS works as normal.

Link to Minimal Reproducible Example

StackBlitz/Git doesn't support symlink (on Windows). See above script.

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: Yes — packages/astro/test/symlink-css.test.ts
• Priority: P3: minor bug. This only affects users who build from symlinked or junction-linked directories, which is a niche workflow. A trivial workaround exists: build from the real (non-symlinked) directory.

The root cause is a path mismatch in the CSS build pipeline. When config.root is a symlink, resolveRoot() uses path.resolve() which does NOT follow symlinks — so internals.pagesByViteID registers pages under the symlink path (e.g. .../linked/src/pages/index.astro). However, Vite/Rollup resolves symlinks by default (resolve.preserveSymlinks is false), so module IDs in the Rollup graph use the real path (e.g. .../real-project/src/pages/index.astro). When the CSS plugin calls getPageDataByViteID() to associate CSS with pages, the lookup fails because the paths don't match, and CSS is silently dropped from the output.

I found a potential fix for this issue. The fix adds fs.realpathSync() in resolveRoot() (packages/astro/src/core/config/config.ts) so that config.root always resolves to the real path, matching Vite's resolved module IDs. A try/catch ensures graceful fallback if the path doesn't exist yet.

Try this fix

You can test this fix right now without waiting for a release:

npm i https://pkg.pr.new/astro@acfa879

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Reproduction

Built a minimal Astro project with a layout importing CSS (global.css) and a scoped <style> block, then built it from both the real directory and a symlinked directory.

• Real directory build: Output HTML contains <style>body{color:#fff;background-color:red;margin:0;padding:2rem}</style> ✅
• Symlinked directory build: Output HTML has no <style> tag and no <link rel="stylesheet"> — CSS is completely missing ❌

Diagnosis

Path flow during build

1. Page registration (static-build.ts): Pages are registered in internals.pagesByViteID using viteID(new URL('./' + component, config.root)). The viteID() function calls fileURLToPath(), which does NOT resolve symlinks. So the key uses the symlink path.

2. CSS collection (plugin-css.ts generateBundle): For each CSS chunk, the plugin walks up the Rollup module graph to find parent pages. Rollup/Vite resolves symlinks by default, so pageInfo.id uses the real path.

3. Lookup failure: getPageDataByViteID(internals, pageInfo.id) does a Map.get() — the real path key doesn't match the symlink path key, returning undefined. CSS is never associated with any page.

Debug evidence

[CSS DEBUG MISS2] pageViteID=/home/.../fixtures/symlink-css/src/pages/index.astro,
                  keys=[/home/.../fixtures/symlink-css-linked/src/pages/index.astro]

The registered key uses symlink-css-linked (symlink) while Rollup's module ID uses symlink-css (real path).

Fix

Changed resolveRoot() in packages/astro/src/core/config/config.ts to resolve symlinks using fs.realpathSync():

 export function resolveRoot(cwd?: string | URL): string {
   if (cwd instanceof URL) {
     cwd = fileURLToPath(cwd);
   }
-  return cwd ? path.resolve(cwd) : process.cwd();
+  const resolved = cwd ? path.resolve(cwd) : process.cwd();
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
 }

Test results

• New test symlink-css.test.ts: 2/2 passing ✅
• Existing CSS tests (0-css.test.ts, css-order.test.ts, css-inline-stylesheets.test.ts, css-assets.test.ts): All passing ✅
• Config tests (config*.test.ts): All passing ✅

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.