Import Attributes

Import attributes provide metadata to the module loader about how to interpret an imported file. They use the with keyword after the module specifier:

// Basic syntax
import data from './file.json' with { type: 'json' };

// The attribute tells the runtime:
// "This file should be parsed as JSON, not JavaScript"

// Without the attribute, importing a .json file
// would either fail or be treated as JavaScript

Import attributes were standardized in ECMAScript 2025 and are supported across all major environments:

Import JSON files directly as ES Modules. The JSON is parsed and available as the default export:

// Import entire JSON file
import config from './config.json' with { type: 'json' };
console.log(config.apiUrl);    // "https://api.example.com"
console.log(config.debug);     // false

// Import in a dynamic import
const pkg = await import('./package.json', {
  with: { type: 'json' }
});
console.log(pkg.default.version); // "1.0.0"

// Re-export from JSON
export { default as config } from './config.json' with { type: 'json' };

Import CSS files as Constructable Stylesheets, ideal for Web Components and Shadow DOM:

// Import a CSS file as a CSSStyleSheet
import styles from './component.css' with { type: 'css' };

// Apply to the document
document.adoptedStyleSheets = [styles];

// Apply to a Shadow DOM (Web Components)
class MyComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.adoptedStyleSheets = [styles];
    shadow.innerHTML = '<p>Styled content</p>';
  }
}
customElements.define('my-component', MyComponent);

Use import attributes with dynamic import() by passing an options object as the second argument:

// Dynamic import with attributes
const config = await import('./config.json', {
  with: { type: 'json' }
});
console.log(config.default);

// Conditional loading based on environment
async function loadTheme(themeName) {
  const theme = await import(
    `./themes/${themeName}.css`,
    { with: { type: 'css' } }
  );
  document.adoptedStyleSheets = [theme.default];
}

// Load JSON data on demand
async function loadLanguage(lang) {
  const translations = await import(
    `./i18n/${lang}.json`,
    { with: { type: 'json' } }
  );
  return translations.default;
}

If your code uses the older assert syntax (import assertions), update to with:

// OLD - import assertions (DEPRECATED)
import data from './data.json' assert { type: 'json' };

// NEW - import attributes (ES2025 STANDARD)
import data from './data.json' with { type: 'json' };

// OLD - dynamic import with assert
const mod = await import('./data.json', {
  assert: { type: 'json' }
});

// NEW - dynamic import with with
const mod = await import('./data.json', {
  with: { type: 'json' }
});

The import attributes mechanism is designed to be extensible. Future types under discussion include: