Imports guide recommends a buggy use of import.meta.url

[delucis]

📚 Subject area/topic

Imports

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/imports/#node-builtins

📋 Description of content that is out-of-date or incorrect

The “Node Builtins” section in the Imports guide is three years old and probably misleading.

It suggests building a relative path to another file like this:

const url = new URL('../../package.json', import.meta.url);

However, import.meta.url’s value varies between dev and build, for example during dev, a page at src/pages/dir/index.astro has an import.meta.url of src/pages/dir/index.astro. However, during a build this might be something like dist/chunks/prerender_CX4g21Zw.mjs instead.

In simple cases this technique can appear to work. For example, in src/pages/index.astro the folder depth is usually the same between dev and build and if you’re loading something at the root level like package.json, you will end up in the right place.

But in pages or components in subdirectories, or when trying to reference siblings in the file structure, you’re very likely to hit inconsistencies between dev and build (not to mention SSR uses of node:fs where you might even be referencing a file outside your project which is missing completely when deployed).

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

https://stackblitz.com/edit/github-9wjfwu?file=src%2Fpages%2Findex.astro

This example shows the documented technique apparently working in dev mode.

If you quit the dev server (Ctrl + C) and preview the build instead by running npm run build && npm run preview, the values in the sub directory page will be off.

[sarah11918]

Do we know what the proper guidance here is? Or just that what we have might set people up for problems?

Would love some tech guidance on this one!