Import-Attribute — Keyword · JavaScript-Referenz

Signatur

import data from "./data.json" with { type: "json" };

Beschreibung

Mit Import-Attributen hängt man an eine import-Deklaration, eine export … from-Anweisung oder einen dynamischen import()-Aufruf ein Objekt mit Schlüssel-Wert-Paaren an. Die Laufzeitumgebung wertet diese Angaben beim Auflösen, Abrufen, Parsen und Auswerten des Moduls aus. Das bekannteste und bisher einzige standardisierte Attribut ist type. Mit type: "json" lädt man JSON-Dateien als Module, mit type: "css" in Browsern CSS-Module-Scripts, die ein CSSStyleSheet liefern.

Der Hauptzweck ist Sicherheit. Im Web bestimmt der Server über den MIME-Typ, wie eine Ressource interpretiert wird. Ohne Attribut könnte ein kompromittierter oder falsch konfigurierter Server statt JSON ausführbares JavaScript ausliefern, und das würde dann ausgeführt. Mit with { type: "json" } legt der importierende Code fest, was er erwartet. Passt der Content-Type der Antwort nicht dazu, schlägt der Import fehl.

Die Attributwerte müssen String-Literale sein, bei statischen Imports sind keine Ausdrücke erlaubt. Unbekannte Attributschlüssel lehnt die Umgebung mit einem SyntaxError bzw. TypeError ab. Außerdem gehört das Attribut zum Modul-Cache-Schlüssel: Dieselbe URL mit unterschiedlichen type-Werten gilt nicht als dasselbe Modul, meist gibt es dann einen Fehler.

Die frühere Syntax mit dem Schlüsselwort assert (Import Assertions) ist veraltet. Neuer Code sollte nur noch with verwenden.

Parameter

Name	Typ	Beschreibung
$type	"json" \| "css" \| string	Erwarteter Modultyp. `"json"` ist in ES2025 standardisiert. `"css"` gilt nur in Browsern (CSS Module Scripts). Ohne Angabe wird das Modul als JavaScript geladen.
$with	Object (Literal)	Das Attribut-Objekt nach dem Modul-Bezeichner, z. B. `with { type: "json" }`. Schlüssel sind Bezeichner oder Strings, Werte müssen String-Literale sein.
$options.with	Object	Beim dynamischen `import(specifier, options)` steht das Attribut-Objekt im zweiten Argument unter dem Schlüssel `with`, z. B. `{ with: { type: "json" } }`.

Rückgabewert

Typ

Modul-Namensraum (statisch) bzw. Promise<Module> (dynamisch)

Beschreibung

Bei JSON-Modulen ist der default-Export der geparste JSON-Wert. Benannte Exporte gibt es dabei nicht. Bei CSS-Modulen ist der default-Export ein CSSStyleSheet. Das dynamische import() gibt ein Promise auf den Modul-Namensraum zurück.

Beispiele

JSON-Konfiguration statisch importieren

// config.json: { "apiUrl": "https://api.example.com", "retries": 3 }
import config from "./config.json" with { type: "json" };

console.log(config.apiUrl);
console.log(config.retries);

https://api.example.com 3

Dynamischer Import mit Attributen (z. B. Übersetzungen nachladen)

const loadMessages = async (lang) => {
  const { default: messages } = await import(`./i18n/${lang}.json`, {
    with: { type: "json" }
  });
  return messages;
};

const de = await loadMessages("de");
console.log(de.greeting);

Hallo Welt

CSS-Modul in einen Web Component übernehmen (Browser)

import sheet from "./button.css" with { type: "css" };

class FancyButton extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: "open" });
    root.adoptedStyleSheets = [sheet];
    root.innerHTML = `<button><slot></slot></button>`;
  }
}

customElements.define("fancy-button", FancyButton);
console.log(sheet instanceof CSSStyleSheet);

true

JSON-Modul weiterexportieren

// constants.js
export { default as countries } from "./countries.json" with { type: "json" };

// app.js
import { countries } from "./constants.js";
console.log(countries.length);

195

// Wichtig · Fallstricke

Veraltete Syntax: import x from \"./a.json\" assert { type: \"json\" } war der Vorgänger. Chrome hat ihn ab Version 126 entfernt, Node.js ab Version 22. Verwende nur noch with.
Nur default-Export: Aus JSON-Modulen kann man nicht benannt importieren. import { apiUrl } from \"./config.json\" with { type: \"json\" } schlägt fehl.
MIME-Typ: Im Browser muss der Server JSON mit application/json ausliefern und CSS mit text/css, sonst wird der Import abgelehnt. Für Module von fremden Ursprüngen gelten die üblichen CORS-Regeln.
Keine Kopie: Das JSON-Objekt wird nur einmal erzeugt und von allen Importeuren geteilt. Änderungen daran sind überall sichtbar. Bei Bedarf mit structuredClone() kopieren.
Browser-Unterstützung: Import-Attribute gehören zur Baseline 2025. Firefox unterstützt sie erst ab Version 138. type: \"css\" gibt es nicht in Node.js, und Firefox unterstützt es bisher nicht. Bundler wie Vite, webpack und esbuild sowie TypeScript (5.3+) verstehen die Syntax.
Andere Attributschlüssel als type werden derzeit mit einem Fehler abgelehnt. So bleibt das Verhalten zwischen den Umgebungen gleich.

Siehe auch

import export JSON.parse() CSSStyleSheet import.defer()