What is the correct way to link to scripts or CSS in public if base is set? Do I need to add the base URL or not?
#Path to public with base set
void trench
vivid stoneBOT
Hi @void trench. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
When linking to assets in the public/ directory while having a base path set in your Astro configuration, you should use absolute URL paths that start with a forward slash /. Astro will automatically handle the base path for you.
Linking to assets in public/ directory
For CSS files in your public/ directory, you would use:
<link rel="stylesheet" href="/styles/global.css" />
For JavaScript files in your public/ directory, you would use:
<script src="/some-external-script.js"></script>
Astro will automatically prepend your configured base path to these URLs during the build process. For example, if your base is set to /my-repo, the rendered HTML will contain:
<link rel="stylesheet" href="/my-repo/styles/global.css" />
<script src="/my-repo/some-external-script.js"></script>
This approach works because Astro handles the URL transformation for you, so you don't need to manually include the base path in your links to files in the public/ directory.
Note that files in the public/ directory are copied to the build folder untouched and won't be processed, bundled, or optimized by Astro as mentioned in the documentation.
Alternative: Using assets in src/ directory
If you want your assets to be processed and optimized by Astro, you should place them in the src/ directory and use ESM imports instead:
---
// For CSS files
import '../styles/utils.css';
---
<script hoist>
// For JavaScript files
import './some-script.js';
</script>
This approach allows Astro to handle the building, bundling, and optimization of your assets as described in the documentation.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
void trench
@vivid stone and what about links? Do I need to add it there?
vivid stoneBOT
Let me check the knowledge base for you again. One moment! :books:
Yes, for links to other pages in your Astro site, you do need to manually include the base path in your URLs when you have a base configured.
Unlike assets in the public/ directory (where Astro automatically handles the base path), internal page links require you to explicitly include the base path:
<a href="/my-repo/about">About</a>
This is clearly stated in the documentation:
When this value is configured, all of your internal page links must be prefixed with your
basevalue:<a href="/my-repo/about">About</a>
Deploy your Astro Site to GitHub Pages
The same requirement is mentioned in the GitLab Pages deployment documentation:
When this value is configured, all of your internal page links must be prefixed with your
basevalue:<a href="/my-repo/about">About</a>
Deploy your Astro Site to GitLab Pages
This is an important distinction to remember: Astro automatically handles the base path for assets in the public/ directory, but for internal navigation links between pages, you must manually include the base path in your href attributes.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
void trench
@vivid stone thanks, I thought this would apply to assets from public as well ❤️🩹
vivid stoneBOT
Let me check the knowledge base for you again. One moment! :books:
You're welcome! I'm glad I could clarify this for you.
To summarize the difference:
-
Assets in
public/: Astro automatically handles the base path for you, so you can use absolute paths like/styles/global.csswithout manually adding the base prefix. -
Internal page links: You must manually include the base path in your URLs (e.g.,
/my-repo/about).
This distinction in how Astro handles different types of paths can be confusing at first, but it's designed to make working with assets more convenient while giving you explicit control over navigation links.