Plugin Hooks Resolvefileurl

Allows customizing how Rolldown resolves URLs of files that were emitted by plugins via this.emitFile. By default, Rolldown will generate code for import.meta.ROLLDOWN_FILE_URL_referenceId that resolves the emitted file relative to import.meta.url. This generates correct absolute URLs for the esm format, and for the cjs format on the node platform where import.meta.url is polyfilled. For the iife and umd formats, import.meta.url is not available and the generated code will not work — Rolldown emits a warning in that case. To support these formats, this hook needs to be implemented to return code that does not rely on import.meta.url. See File URLs for more details and an example.

This hook can be used to customize the behavior of import.meta.ROLLDOWN_FILE_URL_referenceId.

The returned string must be a single JavaScript expression. Also the returned expression must be side-effect free. If the URL is not used in the code, Rolldown will remove it.

Rolldown additionally accepts import.meta.ROLLDOWN_FILE_URL_referenceId_urlId, where urlId is an arbitrary identifier of your choosing. It is passed to this hook as args.urlId, letting a single plugin resolve the same emitted file differently depending on the reference. The urlId API is experimental and may change in minor versions. The urlId is not available on the Rollup-compatible ROLLUP_FILE_URL_ alias. Use only ASCII identifier characters in a urlId: letters, digits, _, and $.

::: tip import.meta.url in the returned string

If the returned string contains import.meta.url, it will be rewritten for non-ESM formats similarly to when import.meta.url is used in the code directly. Unlike Rolldown, Rollup outputs import.meta.url as-is.

:::

Example

The following plugin will always resolve all files relative to the current document:

function resolveToDocumentPlugin() {
  return {
    name: 'resolve-to-document',
    resolveFileUrl({ fileName }) {
      return `new URL(${JSON.stringify(fileName)}, document.baseURI).href`;
    },
  };
}