rollup-plugin-template-postcss

1.3.0 verified Fri May 01 auth: no javascript

A Rollup plugin that processes CSS template literals (including LitElement's css tag) through PostCSS. Current stable version is 1.3.0. The plugin iterates over all matched JavaScript/TypeScript files, extracts CSS template literals, and runs them through PostCSS with user-provided plugins. It supports custom tag names (e.g., 'css'), include/exclude globs, and works with Vite. Unlike related plugins, it leverages PostCSS's plugin ecosystem, making it extensible for minification (cssnano), Tailwind CSS v4, Autoprefixer, and more. Peer dependency on postcss ^8.4.40. Ship TypeScript types.

Common errors

error The plugin is not working: CSS is not transformed. ↓

cause The template literal is not tagged (missing css tag) or not matching the specified 'tags' option.

fix

Use a tagged template literal: import { css } from 'lit'; const styles = css...; Or set tags: ['css', 'myTag'] if using custom tag.

error Error: Cannot find module 'postcss' ↓

cause postcss is a peer dependency and must be installed separately.

fix

Run npm install --save-dev postcss

error SyntaxError: Unexpected token 'export' ↓

cause The plugin is ESM-only and cannot be required with require().

fix

Use import { templatePostcss } from 'rollup-plugin-template-postcss' in an ESM context or configure Rollup for ESM.

error TypeError: templatePostcss is not a function ↓

cause Incorrect import: using default import instead of named import.

fix

Use import { templatePostcss } from 'rollup-plugin-template-postcss'

Warnings

breaking In v1.2.0, the plugin was refactored to use tsdown. The import path remains the same, but the plugin options type may have changed. Ensure you are using the correct option names. ↓

fix Update your configuration to match the documented options in v1.3.0 README.

deprecated Using a string for the 'tags' option is deprecated as of v1.2.0; now it should be an array of strings. ↓

fix Change tags: 'css' to tags: ['css']

gotcha The plugin processes only tagged template literals. Untagged template literals (e.g., `some css`) will not be transformed. You must use a CSS tag like css`` or a custom tag specified in options. ↓

fix Ensure your CSS template literals are tagged: e.g., import { css } from 'lit'; const styles = css`...`;

breaking Version 1.0.0 changed the export from a default export to a named export 'templatePostcss'. Old code using import templatePostcss from 'rollup-plugin-template-postcss' will break. ↓

fix Change import statement to import { templatePostcss } from 'rollup-plugin-template-postcss'

Install

npm install rollup-plugin-template-postcss

yarn add rollup-plugin-template-postcss

pnpm add rollup-plugin-template-postcss

Imports

templatePostcss

wrong

const templatePostcss = require('rollup-plugin-template-postcss')

correct

import { templatePostcss } from 'rollup-plugin-template-postcss'

ESM-only; named export, not default export

TemplatePostcssOptions

wrong

import { TemplatePostcssOptions } from 'rollup-plugin-template-postcss'

correct

import type { TemplatePostcssOptions } from 'rollup-plugin-template-postcss'

Type import for TypeScript users; import type {} is required for type-only imports

rollup-plugin-template-postcss

wrong

import templatePostcss from 'rollup-plugin-template-postcss'

correct

import { templatePostcss } from 'rollup-plugin-template-postcss'

Default import does not exist; always use named import

Quickstart

Basic Rollup config using rollup-plugin-template-postcss with cssnano to minify CSS template literals in LitElement components.

import { templatePostcss } from 'rollup-plugin-template-postcss';
import cssnano from 'cssnano';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    templatePostcss({
      tags: ['css'],
      include: ['**/*.js', '**/*.ts'],
      exclude: ['node_modules/**'],
      plugins: [
        cssnano({
          preset: 'default'
        })
      ]
    })
  ]
};