postcss-lit

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

For example:

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

Install

`sh
npm i -D postcss-lit
`

Usage with PostCSS

In your postcss.config.js:

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

$3

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

`ts
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:

`js
// 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):

`ts
{
"customSyntax": "postcss-lit"
}
`

Or with the CLI:

`sh
stylelint --custom-syntax postcss-lit
`

$3

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:

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

Usage with tailwind

In your postcss.config.js:

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

In your tailwind.config.js:

`ts
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:

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

render() {
return html

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.

$3

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:

`ts
// postcss-lit-disable-next-line
csssome 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:

`ts
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:

`ts
// 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):

`ts
// 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:

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

The available options are listed
here.