{"id":12842,"library":"astro-relative-links","title":"Astro Relative Links Integration","description":"This Astro integration, currently at version 0.4.2, automatically converts absolute and `base`-relative paths within an Astro project to truly relative links during the build process. It addresses a common need for static sites that might be deployed to subdirectories or file systems where absolute paths can break. The project maintains a fairly active release cadence, providing fixes for bugs (e.g., Windows path issues, URL pathname spaces) and adding support for various HTML elements (like `video` poster, embedded styles) and other Astro ecosystem tools (like `astro-compress`, `astro-islands`). Its key differentiator is simplifying deployment flexibility for Astro sites by ensuring all assets, links, and resources are referenced relatively, eliminating the need for complex `base` path handling at runtime. It requires Astro version 3.0.0 or higher.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/ixkaito/astro-relative-links","tags":["javascript","astro","withastro","astro-component","astro-integration","renderer","relative-link","typescript"],"install":[{"cmd":"npm install astro-relative-links","lang":"bash","label":"npm"},{"cmd":"yarn add astro-relative-links","lang":"bash","label":"yarn"},{"cmd":"pnpm add astro-relative-links","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Astro integration runtime and API compatibility.","package":"astro","optional":false}],"imports":[{"note":"The integration is provided as a default export, returning the integration function. Astro configuration files (astro.config.*) are typically ESM.","wrong":"import { relativeLinks } from 'astro-relative-links';\nconst relativeLinks = require('astro-relative-links');","symbol":"relativeLinks","correct":"import relativeLinks from 'astro-relative-links';"}],"quickstart":{"code":"import { defineConfig } from 'astro/config';\nimport relativeLinks from 'astro-relative-links';\n\nexport default defineConfig({\n  // Set your base path if needed, astro-relative-links will handle it\n  // base: '/my-subdirectory',\n  integrations: [relativeLinks()],\n  // Other Astro configurations...\n});","lang":"typescript","description":"Demonstrates how to import and register the `astro-relative-links` integration in `astro.config.mjs` to enable relative path generation for all build outputs."},"warnings":[{"fix":"Upgrade your Astro project to version 3.0.0 or higher, or use an older version of `astro-relative-links` (e.g., <0.4.2) compatible with your Astro version.","message":"Version 0.4.2 and later of `astro-relative-links` requires Astro v3.0.0 or higher as a peer dependency. Projects on older Astro versions will fail to build or run with this integration version.","severity":"breaking","affected_versions":">=0.4.2"},{"fix":"Upgrade to version 0.3.5 or newer to ensure correct handling of paths with spaces.","message":"Paths containing spaces in URLs could lead to incorrect relative link generation on older versions, potentially resulting in broken links or assets.","severity":"gotcha","affected_versions":"<0.3.5"},{"fix":"Upgrade to version 0.3.2 or newer for improved Windows compatibility and reliable path handling.","message":"Users on Windows operating systems might have experienced bugs with path resolution, leading to broken relative links or assets not being found in versions prior to 0.3.2.","severity":"gotcha","affected_versions":"<0.3.2"},{"fix":"Upgrade to version 0.4.0 or newer for full support of URL processing within embedded `<style>` tags.","message":"URLs within embedded `<style>` tags were not consistently processed in versions prior to 0.4.0, which could result in broken asset paths for inline styles.","severity":"gotcha","affected_versions":"<0.4.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using the correct ESM default import: `import relativeLinks from 'astro-relative-links';`","cause":"Attempting to use `astro-relative-links` as a named export or using CommonJS `require()` syntax in an ESM context.","error":"TypeError: astro-relative-links is not a function"},{"fix":"Run `npm install astro-relative-links` or `pnpm install astro-relative-links` or `yarn add astro-relative-links` to install the package.","cause":"The package is not installed or incorrectly referenced in your `astro.config.mjs`.","error":"Error: Cannot find module 'astro-relative-links' or its corresponding type declarations."},{"fix":"Upgrade Astro to version 3.0.0 or later: `npm install astro@latest` or `pnpm update astro` or `yarn upgrade astro`.","cause":"`astro-relative-links` version 0.4.2 or higher requires Astro 3.0.0+. Your current Astro version is incompatible.","error":"Peer dependency 'astro@^3.0.0' not installed."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}