import.meta — Keyword · JavaScript-Referenz

Signatur

import.meta

Beschreibung

import.meta ist eine Meta-Eigenschaft, also keine gewöhnliche Variable und kein Objekt, auf das man per import zugreift. Sie ist nur innerhalb von ES-Modulen verfügbar und liefert ein Objekt mit Informationen über das gerade ausgeführte Modul. Welche Eigenschaften dieses Objekt hat, legt nicht ECMAScript fest, sondern die jeweilige Host-Umgebung (Browser, Node.js, Deno, Bundler).

Die wichtigsten Eigenschaften sind:

import.meta.url: die vollständige URL des Moduls (im Browser https://…, in Node.js file:///…). Diese Eigenschaft ist in allen Umgebungen vorhanden.
import.meta.resolve(specifier): löst einen Modul-Bezeichner relativ zum aktuellen Modul zu einer absoluten URL auf, ohne das Modul zu laden (Browser, Node.js 20.6+).
import.meta.dirname und import.meta.filename: Ordner- und Dateipfad des Moduls. Die gibt es nur in Node.js (ab 20.11/21.2) und sie ersetzen __dirname/__filename aus CommonJS.
import.meta.env, import.meta.hot, import.meta.glob: Erweiterungen von Bundlern wie Vite, die nicht standardisiert sind.

In der Praxis braucht man import.meta.url vor allem, um Ressourcen (Bilder, Worker, JSON, WASM) relativ zur Moduldatei statt relativ zur HTML-Seite oder zum Arbeitsverzeichnis zu laden. Dafür nutzt man new URL('./datei', import.meta.url). So funktionieren Module unabhängig davon, wo sie eingebunden werden.

Rückgabewert

Typ

object

Beschreibung

Ein Objekt mit Prototyp null, das Modul-Metadaten wie url (string) und, je nach Umgebung, resolve(), dirname, filename enthält. Innerhalb eines Moduls ist es immer dasselbe Objekt, und es lässt sich verändern.

Beispiele

Modul-URL auslesen und Ressource relativ laden (Browser)

// datei: /js/widgets/chart.js, eingebunden per <script type="module">
console.log(import.meta.url);

// JSON relativ zur Moduldatei laden, nicht relativ zur HTML-Seite
const configUrl = new URL('./config.json', import.meta.url);
const config = await fetch(configUrl).then((res) => res.json());
console.log(configUrl.href);

https://example.com/js/widgets/chart.js https://example.com/js/widgets/config.json

__dirname-Ersatz in Node.js-ES-Modulen

// datei: /app/src/server.mjs
import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';

// Ab Node.js 20.11 direkt verfügbar:
console.log(import.meta.dirname);

// Portabler Fallback für ältere Versionen:
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const template = await readFile(path.join(__dirname, 'views', 'index.html'), 'utf8');
console.log(template.length > 0);

/app/src true

Web Worker relativ zum Modul starten

// Bundler wie Vite oder webpack erkennen dieses Muster und bündeln den Worker mit
const worker = new Worker(new URL('./rechner.worker.js', import.meta.url), {
  type: 'module'
});

worker.postMessage({ zahlen: [1, 2, 3] });
worker.addEventListener('message', (event) => console.log('Summe:', event.data));

Summe: 6

Bezeichner mit import.meta.resolve() auflösen

// Mit Import-Map: { "imports": { "lodash": "/vendor/lodash-es/lodash.js" } }
const lodashUrl = import.meta.resolve('lodash');
console.log(lodashUrl);

// Relativer Pfad, das Modul wird dabei nicht geladen
console.log(import.meta.resolve('./utils.js'));

https://example.com/vendor/lodash-es/lodash.js https://example.com/js/utils.js

// Wichtig · Fallstricke

Nur in Modulen erlaubt: In klassischen Skripten (ohne type=\"module\") und in CommonJS-Dateien löst import.meta schon beim Parsen einen SyntaxError aus („Cannot use 'import.meta' outside a module“). Auch in einem dynamisch geladenen Code-String per eval() ist es nicht verfügbar.
Keine Destrukturierung von import: import ist kein Objekt. const { meta } = import ist ungültig, erlaubt ist nur die Schreibweise import.meta.
URL statt Pfad: import.meta.url ist eine URL (file:///C:/…), kein Dateipfad. Unter Windows führt das naive Abschneiden von file:// zu falschen Pfaden, deshalb fileURLToPath() verwenden.
Umgebungsabhängig: dirname/filename gibt es nur in Node.js (20.11+), import.meta.env nur in Bundlern wie Vite. Wer solchen Code ohne Bundler ausführt, bekommt undefined.
Kompatibilität: import.meta.url läuft in Chrome 64+, Firefox 62+, Safari 11.1+ und Node.js 10.4+. import.meta.resolve() gibt es in Chrome 105+, Firefox 106+, Safari 16.4+ und Node.js 20.6+ (synchron).
Das Objekt lässt sich verändern, eigene Eigenschaften daran anzuhängen gilt aber als schlechter Stil, weil es Konflikte mit künftigen Host-Erweiterungen geben kann.

Siehe auch

import export new.target Import-Attribute import.defer()