[Draft] Relative path handling in Astro

[jonathantneal]

Relative path handling in Astro

Astro should make it easier to reference images and assets relative to the source file.

Examples:

<img
  alt="Clock"
  local:src="./my-kitten.avif"
  local:srcset="
    ./my-kitten.avif 1x,
    ./[email protected]
  "
/>

---
import Kitten1x from './my-kitten.avif' assert { type: "url" }
import Kitten2x from './[email protected]' assert { type: "url" }
import linkToScript from './script.js' assert { type: "url" }
---

Background

In Astro HTML, it’s not always easy to know where a relative path points to.

<img src="./kitten.avif" alt="kitty" />

If a relative path is used inside of a component, then it might appear to be a reference to something relative to that component in the source. Instead, the path will be relative to the URL where the component was used in the final output.

Goals

• Provide an intuitive way to reference locations relative to the source file.
• Provide an intuitive way to reference early (in Frontmatter) and late (in HTML).

Non Goals

• Certain implementation details like API naming, argument shape, etc., because that can be decided later.
• Issues with relative 'links' that start with /, because it’s much more complicated.
  • A link starting with / is a relative link, while a path starting with / is an absolute path.
  • Vite 'muddies' this distinction by allowing / to be used as a relative link, or as an absolute path, or as a project relative path.
  • This RFC focuses on relative links that are also relative paths and calls them 'paths', for simplicity.
• An image component, because it’s much more complicated.
  • This RFC just happens to use a lot of image examples for simplicity.
  • Relative paths also affect <a>, <link>, <script>, etc. and Astro users continue to face issues with these ^{1 2 3}.
  • An image component could be a followup to this, focusing on other image-related issues like transformation & compression.

---

Current Solutions:

Astro currently supports two solutions; one for 'late' resolution in the HTML block and one for 'early' resolution in the Frontmatter block.

Relative URLs in Astro.resolve

Current Solution 1 for late resolution

To author a relative path that is relative to the source, use Astro.resolve in Astro HTML.

<!-- src/components/my-kitten.astro -->
<a href={Astro.resolve('./my-kitten.avif')}>
  <img src={Astro.resolve('./my-kitten.avif')} />
</a>

Pros:

• This generates a path relative to the source that remains true in the final output.
• The path stays written alongside its context.
• This does not break the way JavaScript works.

Cons:

• The author must introduce a JavaScript block into their Astro HTML.
• The JS block interupts the flow of well-formed HTML.
  • This is even more problematic when srcset is used:

    <img
      alt="Clock"
      src={Astro.resolve('./my-kitten.avif')}
      srcset=`
        ${Astro.resolve('./my-kitten.avif')} 1x,
        ${Astro.resolve('./[email protected]')}
      `
    />

Relative URLs in JavaScript Imports

Current Solution 2 for early resolution

To author a relative path that is relative to the source, use an import in Astro Frontmatter.

---
import Kitten1x from './my-kitten.avif'
import Kitten2x from './[email protected]'
---
<img
  alt="Clock"
  src={Kitten1x}
  srcset=`
    ${Kitten1x} 1x,
    ${Kitten1x}
  `
/>

Pros:

• This generates a path relative to the source that remains true in the final output.
• The JS block interupts the flow of well-formed HTML much less than Astro.resolve.

Cons:

• The author must introduce a Frontmatter block into their file and a JavaScript block into their Astro HTML.
  • In cases like srcset, this still lacks cohesiveness with HTML.
• The author must move their URL away from its context.
• The author must give a meaningful variable name to the URL.
• This breaks the way JavaScript works.
• This prevents certain kinds if relative paths to be imported.
  • This is even more problematic if the asset might also be import-able to JS:

    ---
    import linkToScript from './script.js'
    ---

---

Proposed Solutions

Astro should continue to support two solutions; one for late resolution in the HTML block and one for early resolution in the Frontmatter block.

Relative URLs in Namespaced Attributes

Proposed Solution 1 for late resolution

To author a relative path that is relative to the source, use a local namespaced attribute.

<img
  alt="Clock"
  local:src="./my-kitten.avif"
  local:srcset="
    ./my-kitten.avif 1x,
    ./[email protected]
  "
/>

The local namespace would resolve relative paths in the attribute value while dropping the namespace from the attribute in the final output.

Pros:

• This generates a path relative to the source that remains true in the final output.
• This source is very cohesive with HTML.
• The author does not need to escape into JavaScript.
  • Which means this also does not break the way JavaScript works.
  • Which means the author does not also need to name any JavaScript variable.

Cons:

• The local namespace would need to be parsed to locate and transform relative paths.
• The 'late' processsing may increase the time it takes Astro to detect relative paths and add them to an asset graph.

Relative URLs in Asserted JavaScript Imports

Proposed solution 2 for early resolution

To author a relative path that is relative to the source, use an import with assertions in Astro Frontmatter.

---
import Kitten1x from './my-kitten.avif' assert { type: "url" }
import Kitten2x from './[email protected]' assert { type: "url" }
import linkToScript from './script.js' assert { type: "url" }
---

These type assertions would communicate how the file should be interpretted by JavaScript.

Pros:

• This generates a path relative to the source that remains true in the final output.
• This respects the way JavaScript works.
• This allows any relative paths to be imported.
• This syntax is permitted by our VSCode extension.

Cons:

• The author must introduce a Frontmatter block into their file and a JavaScript block into their Astro HTML.
  • In cases like srcset, this still lacks cohesiveness with HTML.
• The author must move their URL away from its context.
• The author must give a meaningful variable name to the URL.
• This syntax is not yet supported by the Astro compiler.

---

Alternative Solutions:

Relative URLs with a Custom Scheme

Alternative solution 1 for late resolution

To author a relative path that is relative to the source, use a local schema.

<img
  alt="Clock"
  src="local:./my-kitten.avif"
  srcset="
    local:./my-kitten.avif 1x,
    local:./[email protected]
  "
/>

Pros:

• This generates a path relative to the source that remains true in the final output.
• This source is very cohesive with HTML.
• The author does not need to escape into JavaScript.
  • Which means this also does not break the way JavaScript works.
  • Which means the author does not also need to name any JavaScript variable.
• The schema could be supported in other APIs (like JavaScript URLs) for consistency.

Cons:

• The local schema would need to be parsed in every attribute to locate and transform relative paths.
• The 'late' processsing may increase the time it takes Astro to detect relative paths and add them to an asset graph.

Relative URLs with Query Parameters

Alternative solution 2 for early resolution

To author a relative path that is relative to the source, use an import with query parameters in Astro Frontmatter.

---
import Kitten1x from './my-kitten.avif?type=url'
import Kitten2x from './[email protected]?type=url'
---

These query parameters communicate how the file should be loaded.

Pros:

• This generates a path relative to the source that remains true in the final output.
• This allows any relative paths to be imported.
• This syntax is permitted by our VSCode extension, and Vite may already support it.

Cons:

• The author must introduce a Frontmatter block into their file and a JavaScript block into their Astro HTML.
  • In cases like srcset, this still lacks cohesiveness with HTML.
• The author must move their URL away from its context.
• The author must give a meaningful variable name to the URL.
• This breaks the way JavaScript works (without assert { type: 'json' }).

---

Open Questions

Should all relative paths without custom syntax warn or throw?

No, Astro HTML should respect well known and well established conventions in HTML. If you intentionally use relative paths and are comfortable with this context, you’ll be very glad to know that Astro won’t make you change valid HTML.

Should Astro Support Multiple Solutions?

Yes, Astro needs to support late resolution and early resolution. For late resolution in Astro HTML, the solution should be cohesive with HTML. For early resolution in Astro Frontmatter, the solution should be cohesive with JavaScript.

How would import assertions work in Astro?

1. The compiler handling Astro Frontmatter would need to pass thru import assertions.
2. The Acorn plugin for import assertions would need to added to Rollup.
3. The Rollup transform handler would need to return the resolved id path when the assertion instructed so.

[FredKSchott]

Yes, Astro needs to support late resolution and early resolution. For late resolution in Astro HTML, the solution should be cohesive with HTML.

In writing #28 I realized that Astro.resolve() and the concept of "late resolution" may be entirely incompatible with SSR. I'll leave it to @matthewp to give any final say here, but I can't think of a way that we could get around this issue:

CSS and JS are bundled based on the known import graph. If Astro.resolve() runs at runtime, it could reference a CSS or JS file that doesn't actually exist in the final build because it wasn't detected as a file entrypoint, and was instead bundled into a larger bundle of CSS or JS. I can't think of a way around this that is compatible with the idea of bundling.

The promise of src vs. public is that we own src completely, and have full ability to bundle and optimize as needed. We make no promises that files in src will exist 1:1 in the final output. You can see this clearly defined here: https://docs.astro.build/core-concepts/project-structure/#src

I mainly want to flag this because you phrased this as an absolute, that Astro needs to support late runtime resolution, but I don't think that this is true, at least for v1.0. Plenty of frameworks get around this limitation today without too much pain, as far as I can tell. This may change your proposal if this ends up to be the case.

[jonathantneal]

Is a non-starter for SSR support

Maybe I should not have written it the way I did. 😓

It’s 'late' in that the compiler needs to analyze HTML attributes.

But if that’s still a 'non-starter' then that seems harsh. If analyzing HTML attributes are a 'non-starter', then I would think that meant analyzing any attribute in HTML is a non-starter. There’d be no support for <script src>, <link href>, which are equivalent uses.

[FredKSchott]

Discussed in person, taking some notes so that we don't lose them!

• "late" should be defined, I had assumed it meant "runtime" but I now understand @jonathantneal meant something more like "scanned out of the component template and not the frontmatter"
• This RFC proposal is really doing two things: 1. Describing what we need to do about the fact that Astro.resolve() will no longer work in a post-SSR world (critical for v1.0), and 2. Sugar for a new local:src syntax that would reduce the boilerplate of using ESM imports for assets (nice to have). It will be much more productive to split this into two different RFCs.
• RE ESM imports + ?url support: It would be helpful to make it explicitly clear that this RFC is aware that import assertions are not yet supported in Vite, and that ?url is not an alternative solution but is actually a short-term solution that would naturally be replaced by import assertions once they're ready. This is an important part of the adoption plan (a new section in our RFC template!) and also will save us from having to revisit this all over again once import assertions are landed in Vite.
• RE The sugar local:src attribute: missing a summary of how it would be implemented, which is really important for deciding if this should be a part of v1.0 or not. Discussed this a bit, and the fact that local:src could compile to a static ESM import in the compiler output, and then require no other changes across the rest of our codebase. This would gel nicely with our larger push to unify Astro behavior and not offer multiple APIs multiple different implementations.
• RE The sugar local:src attribute for images: Since we don't have an image component yet, it's not out of the question to just say that images must live in public/ and be referenced by absolute path/URL (not resolved by Astro). This has its drawbacks but would solve the "how do dynamic run-time asset references" work. This is what Next.js does, and would be more than viable for v1.0 imo. Most importantly, it would buy us time to come up with the proper solution to solve with our own image component.

[jonathantneal]

Thanks for the great writeup. Agreed on all parts. One new thing I learned, tho –

It would be helpful to make it explicitly clear that this RFC is aware that import assertions are not yet supported in Vite

After we chatted, I saw that Vite is receptive to these, but maybe expecting us to do the work. Not sure if that factors in positively or negatively. 😅

[matthewp]

One issue with import imgUrl from './image.png'; is that it will give you an absolute path like /src/component/image.png. This works fine in dev but won't for supporting subpath deployments. In 0.21 we update URLs to be relative in the final output, but we don't want to do that any more in 1.0. This might just be a Vite setting to append the appropriate subpath though.

[FredKSchott]

I think this is a Vite setting! at least, I think our subpath-during-dev behavior was inspired by them

[matthewp]

@jonathantneal I was confused by this discussion's title:

Markdown Route Generation Proposal

Is this a mistake in copy/pasting? I think this is unrelated to the markdown idea, no?

[jonathantneal]

Good catch. Fixed!

[matthewp]

I think the local: sugar (assuming it is implemented as adding an import statement) would both be an easy thing to implement and would go along way with selling the removal of Astro.resolve.

[matthewp]

I think we should turn this into an RFC and include deprecating Astro.resolve as part of it.

[tohagan]

In case anyone should pass by: Astro,resolved() was removed in Astro v2.

• https://docs.astro.build/en/guides/upgrade-to/v2/#removed-astroresolve