import.meta.resolve() — Keyword · JavaScript-Referenz

Signatur

import.meta.resolve(moduleName)

Beschreibung

import.meta.resolve() ist eine Funktion auf dem import.meta-Objekt eines ES-Moduls. Sie wandelt einen Modul-Bezeichner (Specifier) wie './utils.js', 'lodash' oder '@app/config' nach denselben Regeln in eine absolute URL um, die auch import und import() verwenden. Dabei werden die URL des aktuellen Moduls (import.meta.url) und im Browser eine eventuell vorhandene Import-Map berücksichtigt.

Anders als import() wird das Modul nicht geladen und nicht ausgeführt. Die Funktion arbeitet synchron und gibt einen String zurück. Nützlich ist das vor allem dann, wenn du eine URL an eine andere API übergeben willst, zum Beispiel an new Worker(), fetch(), ein <link rel="modulepreload"> oder ein Asset-Tag. Außerdem kannst du damit prüfen, wohin ein Bare Specifier laut Import-Map zeigt.

Im Vergleich zu new URL('./datei.js', import.meta.url) hat import.meta.resolve() einen wichtigen Vorteil: Es versteht auch Bare Specifier und Import-Maps. new URL() löst dagegen nur relative und absolute URLs auf.

Parameter

Name	Typ	Default	Beschreibung
$moduleName Pflicht	string		Der aufzulösende Modul-Bezeichner: relativ (`'./a.js'`, `'../lib/b.js'`), absolut (`'https://…'`, `'/src/c.js'`) oder ein Bare Specifier (`'lodash'`), der über eine Import-Map bzw. unter Node.js über `node_modules`/`exports` aufgelöst wird. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

string

Beschreibung

Die vollständig aufgelöste absolute URL als String, z. B. 'https://example.com/js/utils.js' oder unter Node.js 'file:///home/app/node_modules/lodash/lodash.js'. Kann der Bezeichner nicht aufgelöst werden, wird ein TypeError ausgelöst.

Beispiele

Relativen Pfad zur absoluten URL auflösen

// Datei: https://example.com/js/main.js
const helperUrl = import.meta.resolve('./helper.js');
const parentUrl = import.meta.resolve('../assets/data.json');

console.log(helperUrl);
console.log(parentUrl);

https://example.com/js/helper.js https://example.com/assets/data.json

Bare Specifier über eine Import-Map auflösen

// In der HTML-Seite:
// <script type="importmap">
//   { "imports": { "chart": "/vendor/chart/4.4.0/chart.esm.js" } }
// </script>

// Datei: https://example.com/js/app.js
const chartUrl = import.meta.resolve('chart');
console.log(chartUrl);

// Modul vorab laden, ohne es auszuführen
const link = document.createElement('link');
link.rel = 'modulepreload';
link.href = chartUrl;
document.head.append(link);

https://example.com/vendor/chart/4.4.0/chart.esm.js

Modul-Worker mit aufgelöster URL starten

// Datei: https://example.com/js/main.js
const worker = new Worker(import.meta.resolve('./workers/rechner.js'), {
  type: 'module'
});

worker.addEventListener('message', (event) => {
  console.log('Ergebnis:', event.data);
});

worker.postMessage({ a: 20, b: 22 });

Ergebnis: 42

Auflösung mit Fehlerbehandlung (Node.js)

// Datei: /home/app/src/index.mjs (Node.js 20.6+)
const tryResolve = (specifier) => {
  try {
    return import.meta.resolve(specifier);
  } catch (err) {
    return `nicht auflösbar: ${err.code ?? err.name}`;
  }
};

console.log(tryResolve('./config.mjs'));
console.log(tryResolve('gibt-es-nicht'));

file:///home/app/src/config.mjs nicht auflösbar: ERR_MODULE_NOT_FOUND

// Wichtig · Fallstricke

Nur in ES-Modulen verfügbar: In klassischen Skripten und CommonJS ist import.meta ein SyntaxError. Im Browser brauchst du <script type="module">, unter Node.js .mjs oder "type": "module".
Keine Existenzprüfung: Im Browser wird nur die URL berechnet. Ob die Datei tatsächlich existiert, wird nicht geprüft. Ein Fehler tritt erst beim Laden auf. Node.js prüft dagegen bei Bare Specifiern, ob das Paket in node_modules vorhanden ist.
Synchron statt asynchron: In aktuellen Umgebungen gibt die Funktion einen String zurück. Ältere Node.js-Versionen hinter --experimental-import-meta-resolve (vor 20.6) lieferten ein Promise und akzeptierten einen zweiten Parameter parent. Diese Variante ist veraltet.
Bare Specifier ohne Import-Map: Im Browser löst ein Aufruf wie import.meta.resolve('lodash') ohne passenden Import-Map-Eintrag einen TypeError aus.
Bundler: Werkzeuge wie Vite, webpack oder esbuild ersetzen den Ausdruck teilweise zur Build-Zeit oder unterstützen ihn nur eingeschränkt. Prüfe das Verhalten im Build-Ergebnis. Als Alternative für relative Assets eignet sich new URL('./datei', import.meta.url), das Bundler breit unterstützen.
Kompatibilität: Chrome/Edge 105+, Firefox 106+, Safari 16.4+, Node.js 20.6+/18.19+, Deno. Für ältere Browser gibt es keinen vollständigen Polyfill.

Siehe auch

import.meta import export Worker import.defer()