Registry / web-framework / astro-relative-links

astro-relative-links

library0.4.2jsnpmunverified

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.

web-framework devops

npm install astro-relative-links

github ↗package ↗

INSTALL

IMPORT

SIG · ASTRO-RELATIVE-LIN

astro-relative-links

web-frameworkjavascriptv0.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

relativeLinks

✓ import relativeLinks from 'astro-relative-links';

✗ import { relativeLinks } from 'astro-relative-links'; const relativeLinks = require('astro-relative-links');

The integration is provided as a default export, returning the integration function. Astro configuration files (astro.config.*) are typically ESM.

Demonstrates how to import and register the `astro-relative-links` integration in `astro.config.mjs` to enable relative path generation for all build outputs.

import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; export default defineConfig({ // Set your base path if needed, astro-relative-links will handle it // base: '/my-subdirectory', integrations: [relativeLinks()], // Other Astro configurations... });

Debug

Known issues

breakingVersion 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.

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.

affects: >=0.4.2

gotchaPaths containing spaces in URLs could lead to incorrect relative link generation on older versions, potentially resulting in broken links or assets.

fix

Upgrade to version 0.3.5 or newer to ensure correct handling of paths with spaces.

affects: <0.3.5

gotchaUsers 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.

fix

Upgrade to version 0.3.2 or newer for improved Windows compatibility and reliable path handling.

affects: <0.3.2

gotchaURLs 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.

fix

Upgrade to version 0.4.0 or newer for full support of URL processing within embedded `<style>` tags.

affects: <0.4.0

Errors

Common errors & fixes

TypeError: astro-relative-links is not a function

Attempting to use `astro-relative-links` as a named export or using CommonJS `require()` syntax in an ESM context.

fix

Ensure you are using the correct ESM default import: `import relativeLinks from 'astro-relative-links';`

Error: Cannot find module 'astro-relative-links' or its corresponding type declarations.

The package is not installed or incorrectly referenced in your `astro.config.mjs`.

fix

Run `npm install astro-relative-links` or `pnpm install astro-relative-links` or `yarn add astro-relative-links` to install the package.

Peer dependency 'astro@^3.0.0' not installed.

`astro-relative-links` version 0.4.2 or higher requires Astro 3.0.0+. Your current Astro version is incompatible.

fix

Upgrade Astro to version 3.0.0 or later: `npm install astro@latest` or `pnpm update astro` or `yarn upgrade astro`.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

astrorequiredRequired peer dependency for Astro integration runtime and API compatibility.

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/ixkaito/astro-relative-links ↗

packagehttps://www.npmjs.com/package/astro-relative-links ↗