rollup-plugin-import-assert

3.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that enables import assertions (formerly import attributes) for CSS and JSON modules, allowing developers to import stylesheets as constructible stylesheets and JSON modules with type assertions. Version 3.0.1 works with Rollup 3+ and requires acorn-import-assertions as a peer dependency. It transforms CSS imports into CSS module scripts for use with adoptedStyleSheets. Compared to alternatives like @rollup/plugin-json or raw CSS imports, this plugin provides standardized import assertion syntax as per the TC39 proposal, but only supports static imports with literal assertion values. It does not handle dynamic imports with dynamic expressions. The package ships TypeScript definitions.

Common errors

error Error: Cannot find module 'acorn-import-assertions' ↓

cause Missing peer dependency acorn-import-assertions

fix

npm install -D acorn-import-assertions

error The requested module 'rollup-plugin-import-assert' does not provide an export named 'default' ↓

cause Using default import when plugin exports named export

fix

Change import to: import { importAssertionsPlugin } from 'rollup-plugin-import-assert'

error [!] Error: Cannot use import assertion with dynamic import with dynamic expression ↓

cause The plugin ignores dynamic imports with template literals or variables

fix

Use a static import with assert syntax or avoid dynamic expressions in the import path.

Warnings

breaking Requires Rollup 3+; not compatible with Rollup 2 ↓

fix Upgrade Rollup to version 3 or later, or use older versions of this plugin (not specified).

gotcha Dynamic imports with dynamic expressions (e.g., import(`./${name}.json`)) are silently ignored ↓

fix Use static imports or ensure the import path is a string literal for assertions to work.

deprecated Import assertions are being renamed to 'import attributes' in the TC39 proposal; future ECMAScript versions may use 'with' instead of 'assert' ↓

fix Watch for future updates; may need to use 'with' syntax in newer versions.

gotcha CSS module script API (adoptedStyleSheets) is only natively supported in Chromium browsers; requires polyfill for other browsers ↓

fix Install construct-style-sheets-polyfill for cross-browser support.

Install

npm install rollup-plugin-import-assert

yarn add rollup-plugin-import-assert

pnpm add rollup-plugin-import-assert

Imports

importAssertionsPlugin

wrong

const importAssertionsPlugin = require('rollup-plugin-import-assert')

correct

import { importAssertionsPlugin } from 'rollup-plugin-import-assert'

ESM-only package, no CommonJS support

importAssertions
```
import { importAssertions } from 'acorn-import-assertions'
```
This is from the peer dependency, but commonly confused as part of the plugin. Must be installed separately.

default (plugin instance)

wrong

import importAssertionsPlugin from 'rollup-plugin-import-assert'

correct

import { importAssertionsPlugin } from 'rollup-plugin-import-assert'

The package uses a named export, not default. Many users mistakenly use default import.

Quickstart

Shows how to install, configure Rollup with acorn-import-assertions and the plugin, and use import assertions for CSS modules.

// Install: npm i -D rollup-plugin-import-assert acorn-import-assertions
// rollup.config.js
import { importAssertionsPlugin } from 'rollup-plugin-import-assert';
import { importAssertions } from 'acorn-import-assertions';

export default {
  input: 'src/index.js',
  output: {
    format: 'esm',
    dir: 'dist',
  },
  acornInjectPlugins: [importAssertions],
  plugins: [importAssertionsPlugin()],
};

// src/index.js
import styles from './styles.css' assert { type: 'css' };
class MyElement extends HTMLElement {
  connectedCallback() {
    this.attachShadow({ mode: 'open' }).adoptedStyleSheets = [styles];
  }
}
customElements.define('my-element', MyElement);