esbuild-plugin-lit

0.1.1 verified Fri May 01 auth: no javascript

An esbuild plugin for importing CSS, SVG, HTML, and XLIFF files as tagged-template literals (lit-html compatible) with optional minification via esbuild, html-minifier, and svgo. Current version 0.1.1, stable release. Differentiators: simplifies LitElement development by eliminating separate build steps for styles and assets; supports TypeScript with provided type declarations; enables direct import of XLIFF localization files without intermediate compilation. Peer dependencies include esbuild, lit, html-minifier, svgo, and txml.

Common errors

error Error: Cannot find module 'html-minifier' ↓

cause Missing optional dependency for HTML minification.

fix

npm install html-minifier --save-dev

error TypeScript error: Cannot find module './styles.css' or its corresponding type declarations. ↓

cause Ambient module declarations not included in tsconfig.

fix

Add "include": ["./node_modules/esbuild-plugin-lit/modules.d.ts"] to tsconfig.json.

error Error: The plugin "lit" requires the "esbuild" package to be installed ↓

cause Missing esbuild peer dependency.

fix

npm install esbuild --save-dev

Warnings

deprecated The default export may change in future versions; prefer named import if available. ↓

fix None needed yet, but monitor package for breaking changes.

gotcha SVG and HTML minification require optional peer dependencies svgo and html-minifier to be installed separately. ↓

fix npm install svgo html-minifier --save-dev

gotcha XLIFF loading requires txml peer dependency and setting esbuild loader to 'text' for .xlf files. ↓

fix npm install txml --save-dev and add `loader: { '.xlf': 'text' }` to esbuild config.

gotcha TypeScript ambient module declarations are not automatically included; you must add them manually in tsconfig. ↓

fix Add `"include": ["./node_modules/esbuild-plugin-lit/modules.d.ts"]` to tsconfig.json.

gotcha The filter regex in plugin options augments the global filter; misconfiguration may cause files not to be processed. ↓

fix Ensure custom filter extends the default by using pattern like /(\.css|\.svg|\.html|\.xlf|\.scss)$/

Install

npm install esbuild-plugin-lit

yarn add esbuild-plugin-lit

pnpm add esbuild-plugin-lit

Imports

default
wrong
```
const litPlugin = require('esbuild-plugin-lit')
```
correct
```
import litPlugin from 'esbuild-plugin-lit'
```
Package uses ESM default export; CommonJS require() works too (compiled by esbuild).

LitPlugin

wrong

import { LitPlugin } from 'esbuild-plugin-lit'

correct

import type { LitPlugin } from 'esbuild-plugin-lit'

LitPlugin is a type export, not a value. Use type import for TypeScript.

Options

import type { Options } from 'esbuild-plugin-lit'

Options type for plugin configuration.

Quickstart

Shows how to set up the plugin with esbuild and import CSS/SVG files as tagged template literals in a LitElement.

const { default: litPlugin } = require('esbuild-plugin-lit');

require('esbuild').build({
  entryPoints: ['index.ts'],
  bundle: true,
  outfile: 'index.js',
  plugins: [litPlugin()],
}).catch(() => process.exit(1));

// index.ts:
import { LitElement, html, css } from 'lit';
import styles from './styles.css';
import icon from './icon.svg';

class MyElement extends LitElement {
  static styles = css`${styles}`;
  render() {
    return html`<div class="icon">${icon}</div>`;
  }
}
customElements.define('my-element', MyElement);