If you’ve ever built a site with Astro and needed to deploy the exact same build to multiple target environments some at the root domain (/) and others in a subfolder (/docs/ or /my-app/). You know the frustration: broken assets.
In our CI/CD setup with Jenkins, we ran into a situation where we needed to deploy the same compiled site to different folder depths. Because Astro defaults to root-absolute paths (/assets/style.css), configuring a static base path in astro.config.mjs didn’t work. One deployment target would always end up with broken CSS, missing images, and dead internal links.
You can solve it with a lightweight Astro integration: astro-relative-links.
The Solution: astro-relative-links
We added the astro-relative-links
It automatically transforms output HTML links during the build step, converting root-absolute paths into relative paths (./ or ../) based on where each HTML file lives.
How to set it up:
1. Install the package:
npm install astro-relative-links
2. Add it to your astro.config.mjs:
import { defineConfig } from 'astro/config';
import relativeLinks from 'astro-relative-links';
export default defineConfig({
integrations: [
relativeLinks()
],
});
The Result
Now, regardless of where the site is served or mounted in your server directory structure, the generated paths adapt dynamically:
HTML
<!-- Output on a top-level page -->
<link rel="stylesheet" href="./_astro/index.b12345.css" />
<!-- Output on a deeply nested page (/blog/posts/first-post) -->
<link rel="stylesheet" href="../../_astro/index.b12345.css" />
That’s all, happy days!