@arcmantle/vite-plugin-import-css-sheet

A Vite plugin that enables the use of TC39 Import Attributes proposal for CSS files. Import CSS files with with { type: 'css' } syntax and get them as CSSStyleSheet objects, perfect for Web Components and Shadow DOM.

Features

• 🚀 Import CSS as CSSStyleSheet: Transform CSS imports into constructable stylesheets
• 🎯 TC39 Standard Syntax: Uses the official with { type: 'css' } syntax
• ⚡ Vite Integration: Seamless integration with Vite's build process
• 🤖 Auto-Import: Automatically inject CSS imports for co-located stylesheets
• 🗜️ CSS Minification: Built-in CSS minification using Lightning CSS
• 🔧 Customizable: Support for custom transformers and additional code injection
• 📦 TypeScript Support: Full TypeScript definitions included
• 🔍 Development Friendly: Watch mode support for CSS file changes

Installation

npm install @arcmantle/vite-plugin-import-css-sheet
# or
pnpm add @arcmantle/vite-plugin-import-css-sheet
# or
yarn add @arcmantle/vite-plugin-import-css-sheet

Usage

Basic Setup

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { importCSSSheet } from '@arcmantle/vite-plugin-import-css-sheet';

export default defineConfig({
  plugins: [
    importCSSSheet()
  ]
});

Import CSS as CSSStyleSheet

Use the TC39 import attributes syntax to import CSS files as CSSStyleSheet objects:

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

// Use with Web Components
class MyComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });

    // Apply the stylesheet to shadow DOM
    shadow.adoptedStyleSheets = [styles];

    shadow.innerHTML = `
      <div class="container">
        <h1>Hello World</h1>
      </div>
    `;
  }
}

customElements.define('my-component', MyComponent);

Lit Integration

Perfect for Lit components:

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import componentStyles from './component.css' with { type: 'css' };

@customElement('my-lit-component')
export class MyLitComponent extends LitElement {
  static styles = [componentStyles];

  render() {
    return html`
      <div class="container">
        <p>Styled with imported CSS sheet!</p>
      </div>
    `;
  }
}

TypeScript Support

Include the provided type definitions in your project:

// In your vite-env.d.ts or types file
/// <reference types="@arcmantle/vite-plugin-import-css-sheet/client" />

This provides proper TypeScript support for CSS imports:

// TypeScript will know this is a CSSStyleSheet
import styles from './styles.css' with { type: 'css' };

Configuration

The plugin accepts several configuration options:

import { importCSSSheet } from '@arcmantle/vite-plugin-import-css-sheet';

export default defineConfig({
  plugins: [
    importCSSSheet({
      // Custom CSS transformers
      transformers: [
        (code, id) => {
          // Custom transformation logic
          return code.replace(/\$primary-color/g, '#007bff');
        }
      ],

      // Additional code to inject
      additionalCode: [
        'console.log("CSS sheet loaded:", sheet);'
      ],

      // Disable minification (enabled by default)
      minify: false
    })
  ]
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | transformers | ((code: string, id: string) => string)[] | [] | Array of functions to transform CSS before converting to stylesheet | | additionalCode | string[] | [] | Additional JavaScript code to inject into the generated module | | minify | boolean | true | Whether to minify CSS using Lightning CSS | | autoImport | object | undefined | Configuration for automatic CSS import injection |

Auto-Import Feature

The auto-import feature automatically detects when a .css file exists alongside your component file and automatically injects the import statement and adds it to your component's static styles property. This is perfect for component-based frameworks like Lit.

How It Works

When you have co-located CSS files:

src/
  ├── my-component.ts
  └── my-component.css

The plugin can automatically transform your component to include the CSS import, eliminating boilerplate.

Auto-Import Configuration

Enable auto-import by providing the autoImport configuration:

import { importCSSSheet } from '@arcmantle/vite-plugin-import-css-sheet';

export default defineConfig({
  plugins: [
    importCSSSheet({
      autoImport: {
        identifier: [
          {
            className: 'LitElement',
            styleName: 'styles',
            position: 'prepend' // or 'append'
          }
        ]
      }
    })
  ]
});

Auto-Import Options

| Property | Type | Required | Description | |----------|------|----------|-------------| | className | string | Yes | The base class name to detect (e.g., 'LitElement', 'HTMLElement') | | styleName | string | Yes | The static property name to inject the stylesheet into (e.g., 'styles') | | position | 'prepend' \| 'append' | No | Where to add the stylesheet in the array. Default: 'prepend' |

Example: Without Auto-Import

// my-component.ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import componentStyles from './my-component.css' with { type: 'css' };

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = [componentStyles]; // Manually added

  render() {
    return html`<div>Hello World</div>`;
  }
}

Example: With Auto-Import

With auto-import enabled, you can omit the import and static property:

// my-component.ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
// Import is automatically injected!

@customElement('my-component')
export class MyComponent extends LitElement {
  // static styles is automatically created/updated!

  render() {
    return html`<div>Hello World</div>`;
  }
}

The plugin automatically transforms this to:

import my_component_styles from './my-component.css' with { type: 'css' };
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = [my_component_styles]; // Auto-injected!

  render() {
    return html`<div>Hello World</div>`;
  }
}

Auto-Import with Existing Styles

If you already have a static styles property, the auto-import will add to it:

// Before transformation
import { LitElement } from 'lit';
import sharedStyles from './shared.css' with { type: 'css' };

export class MyComponent extends LitElement {
  static styles = [sharedStyles];
}

// After transformation (with position: 'prepend')
import my_component_styles from './my-component.css' with { type: 'css' };
import { LitElement } from 'lit';
import sharedStyles from './shared.css' with { type: 'css' };

export class MyComponent extends LitElement {
  static styles = [my_component_styles, sharedStyles]; // Prepended
}

// After transformation (with position: 'append')
export class MyComponent extends LitElement {
  static styles = [sharedStyles, my_component_styles]; // Appended
}

Multiple Class Support

You can configure auto-import for multiple base classes:

importCSSSheet({
  autoImport: {
    identifier: [
      {
        className: 'LitElement',
        styleName: 'styles',
        position: 'prepend'
      },
      {
        className: 'CustomBaseElement',
        styleName: 'styleSheets',
        position: 'append'
      },
      {
        className: 'MyFrameworkComponent',
        styleName: 'componentStyles'
      }
    ]
  }
})

When Auto-Import Triggers

The auto-import feature only activates when:

1. A .css file exists with the same name as your component file
2. Your class extends one of the configured base classes
3. The file is a supported type (.ts, .tsx, .js, .jsx, .mts, .mjs)

Position: Prepend vs Append

The position option controls CSS cascade order:

• prepend (default): Component styles come first, can be overridden by later styles
• append: Component styles come last, override earlier styles

// position: 'prepend'
static styles = [componentStyles, baseStyles, themeStyles];
//                ^^^^^^^^^^^^^^ auto-imported (lowest specificity)

// position: 'append'
static styles = [baseStyles, themeStyles, componentStyles];
//                                        ^^^^^^^^^^^^^^ auto-imported (highest specificity)

Benefits of Auto-Import

✅ Less Boilerplate: No need to manually import and assign stylesheets ✅ Co-location: Encourages keeping styles next to components ✅ Consistency: Automatic naming conventions ✅ Flexibility: Works with existing manual imports ✅ Type-Safe: Full TypeScript support with source maps

Plugin Architecture

1. Detection: The plugin scans your source files for CSS imports using the with { type: 'css' } syntax
2. Virtual Modules: Creates virtual modules for CSS files that need to be converted
3. Transformation: Processes CSS through any custom transformers and minification
4. Code Generation: Generates JavaScript code that creates a CSSStyleSheet object
5. Export: Exports the stylesheet as the default export

Browser Support

This plugin generates code that uses the Constructable Stylesheets API:

• Chrome/Edge 73+
• Firefox 101+
• Safari 16.4+

For older browsers, consider using a polyfill.

Why Use This Plugin?

Traditional CSS Imports

// Traditional Vite CSS import (injects into document)
import './styles.css';

With This Plugin

// Get CSS as CSSStyleSheet object
import styles from './styles.css' with { type: 'css' };

// Perfect for Shadow DOM
shadowRoot.adoptedStyleSheets = [styles];

Benefits

• Encapsulation: Styles don't leak into global scope
• Performance: No style injection/removal overhead
• Standards Compliant: Uses official TC39 syntax
• Shadow DOM Ready: Perfect for Web Components
• Tree Shakable: Only load styles when needed

Examples

Multiple Stylesheets

import baseStyles from './base.css' with { type: 'css' };
import themeStyles from './theme.css' with { type: 'css' };
import componentStyles from './component.css' with { type: 'css' };

// Combine multiple stylesheets
element.shadowRoot.adoptedStyleSheets = [
  baseStyles,
  themeStyles,
  componentStyles
];

Dynamic Style Loading

// Conditional style loading
const isDark = document.body.classList.contains('dark-theme');
const themeStyles = isDark
  ? await import('./dark-theme.css' with { type: 'css' })
  : await import('./light-theme.css' with { type: 'css' });

shadowRoot.adoptedStyleSheets = [baseStyles, themeStyles.default];

Development

# Install dependencies
pnpm install

# Run demo in development mode
pnpm dev

# Build the plugin
pnpm build

Requirements

• Node.js >= 22
• Vite >= 7.0.0

Dependencies

• lightningcss: Fast CSS transformer and minifier for CSS processing

License

Apache-2.0

Contributing

This package is part of the Arcmantle Weave monorepo. Contributions are welcome! .......