postcss-lit

A PostCSS and stylelint custom syntax for parsing CSS inside lit templates.

For example:

class MyElement extends LitElement {
  static styles = css`
    .foo { color: hotpink; }
  `;
}

Install

npm i -D postcss-lit

Usage with PostCSS

In your postcss.config.js:

module.exports = {
  syntax: 'postcss-lit',
  plugins: [...]
};

PostCSS with webpack

If you use webpack to execute postcss, you must ensure the right order of loaders, like so:

module.exports = {
  entry: './src/my-element.ts',
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: ['postcss-loader', 'ts-loader'],
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.ts']
  },
  output: {
    filename: 'bundle.js'
  }
};

This is important as postcss will transform your CSS before typescript transpiles to JS (which is what you want to happen).

Usage with Vite or Rollup

If you use vite or rollup, you can simply use the rollupPostCSSLit plugin:

// rollup.config.js
// IMPORTANT: since we're still CommonJS, use a default import
import postcssLit from 'postcss-lit';

export default {
  plugins: [
    postcssLit.rollupPostCSSLit({
      // process only files in the `src` directory
      globInclude: 'src/**/*.{js,ts}',
      // exclude files with `-legacy.js` in their name
      globExclude: '**/*-legacy.js'
    })
  ]
}

The plugin will transform your CSS from template literals inside JS/TS files using PostCSS. It will also automatically use local PostCSS config files.

You can use the optional globInclude and globExclude plugin options to specify which files should be processed by PostCSS.

Usage with stylelint

In your .stylelintrc.json (or other stylelint config file):

{
  "customSyntax": "postcss-lit"
}

Or with the CLI:

stylelint --custom-syntax postcss-lit

Usage with vscode-stylelint

In order to make the vscode-stylelint extension work with this syntax correctly, you must configure it to validate JS and/or TypeScript files.

You can do this by following these instructions.

For example:

{
  "stylelint.validate": ["css", "javascript", "typescript"]
}

Usage with tailwind

In your postcss.config.js:

module.exports = {
  syntax: 'postcss-lit',
  plugins: {
    tailwindcss: {}
  }
};

In your tailwind.config.js:

const {tailwindTransform} = require('postcss-lit');

module.exports = {
  content: {
    files: ['./src/**/*.{js,ts}'],
    transform: {
      ts: tailwindTransform
    }
  }
};

You may then use tailwind's directives and classes in your elements:

class MyElement extends LitElement {
  static styles = css`
    @tailwind base;
    @tailwind utilities;
  `;

  render() {
    return html`
      <div class="text-xs">Small text</div>
    `;
  }
}

You must specify all tailwind directives you intend to use in your CSS, otherwise their replacement CSS will be incorrectly appended to the end of the document.

For example, in the code above, @tailwind base and @tailwind utilities were specified to make text-xs available. Without them, the code would not build.

Tailwind with webpack

See the same advice as with postcss standalone, here.

Disable specific templates

You can use postcss-lit-disable-next-line to disable a particular template from being processed:

// postcss-lit-disable-next-line
css`some template`;

These templates will be left as-is and won't make their way through postcss.

Note on expressions/interpolation

Often you may end up with expressions in your templates. For example:

css`
  .foo {
    color: ${expr};
  }
`;

These can be very difficult to support at build-time since we have no useful run-time information for what the expression might be.

Due to these difficulties, we officially support complete syntax being interpolated, though other cases may still work.

A few supported examples:

// Entire selector bound in
css`
  ${expr} {
    color: hotpink;
  }
`;

// Entire property bound in
css`
  .foo {
    ${expr}: hotpink;
  }
`;

// Entire value bound in
css`
  .foo {
    color: ${expr};
  }
`;

// Entire statement bound in
css`
  .foo {
    ${expr}
  }
`;

// Entire block bound in
css`
  .foo {}
  ${expr}
`;

And a few unsupported examples (though some may work, they are not officially supported):

// Part of a selector bound in
css`
  .foo, ${expr} {
    color: hotpink;
  }
`;

// Part of a value bound in
css`
  .foo {
    color: hot${expr};
  }
`;

// Part of a property bound in
css`
  .foo {
    col${expr}: hotpink;
  }
`;

In cases we fail to parse, we will raise a warning in the console and skip the template (i.e. leave it untouched and won't process it).

You can then use a // postcss-lit-disable-next-line comment to silence the warning.

Custom babel options

You may customise the babel options via your package.json:

{
  "postcss-lit": {
    "babelOptions": {
    }
  }
}

The available options are listed here.