Announcing production-ready linting for styled-components

Interpolation tagging, TypeScript support, a shared config and much more make this our most stable release yet!

Over the summer the team (led by Emil Goldsmith and Ismay Wolff) has been working hard on the stylelint processor for styled-components to make it production–ready. Today, we’re very excited to announce stylelint-processor-styled-components@1.0.0: reliably lint the CSS in your styled-components with the full power of stylelint!

If you’re new to the world of linters, stylelint is the most popular tool to catch errors in your CSS before they happen. It’s invaluable to make sure your code works by detecting mistakes such as invalid colors, shorthands and many more. (150+ rules, excluding plugins!)

With the processor we enable you to use the mature ecosystem around stylelint to make sure your styled-components CSS is as solid as can be.

Note: If you’ve tried the processor before but had issues, give it another go now—you’ll be surprised!

TL;DR

A short list of some things we worked on over the past months:

• Interpolation tagging to avoid CSS parsing errors with JS interpolations
• A brand new shared stylelint configuration to configure a couple of rules to fit with styled-components’ style of writing CSS
• Support for TypeScript (Flow has always been supported)
• Better support for alternative
• Full support for styled-components v2, including API additions like .attrs and .extend
• An extensive test suite with 100% coverage to cover as many edge cases as possible
• …and a whole bunch of other improvements

Read further for details about the improvements, or jump into the changelog.

Usage

If you want to give the processor a try, follow these three steps:

1. Installation

You need:

• stylelint (duh)
• stylelint-processor-styled-components to extract styles from styled-components
• stylelint-config-styled-components to configure a couple of rules to fit with styled-components’ style of writing CSS
• Your favorite stylelint config! (for example stylelint-config-standard)

(npm install --save-dev
  stylelint
  stylelint-processor-styled-components
  stylelint-config-styled-components
  stylelint-config-standard)

2. Setup

Add a .stylelintrc file to the root of your project:

{
  "processors": ["stylelint-processor-styled-components"],
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-styled-components"
  ],
  "syntax": "scss"
}

3. Run it!

The last step is to run stylelint on all of your components. Depending on your folder structure the command looks something like this:

$ stylelint 'src/**/*.js'

Details

Interpolation Tagging

Sometimes stylelint throws an error (e.g. CssSyntaxError) even though nothing is wrong with your code. This is often due to an interpolation, more specifically the fact that the processor doesn't know what you're interpolating.

When you have interpolations in your styles the processor can’t know what they are, so it makes a good guess and replaces them with a syntactically equivalent placeholder value. Since stylelint is not a code flow analysis tool this doesn't cover all edge cases and the processor will get it wrong every now and then.

Interpolation tagging allows you to tell the processor what an interpolation is; it can then replace it with a syntactically correct value. For example:

const something = 'background';
const Button = styled.div`
  // Tell the processor that "something" is a property
  ${/* sc-prop */ something}: papayawhip;
`

Now the processor knows that the something interpolation is a property, and it can replace something with a property for stylelint.

Shared stylelint configuration

When linting styled components, a couple of stylelint rules throw errors that cannot be prevented, e.g. no-empty-source or no-missing-end-of-source-newline. Also, there are a couple of rules we need to enforce, e.g. no-vendor-prefix. (styled-components automatically vendor-prefixes your code, so you don't need to do it manually)

To configure these rules around styled-components’ style of writing CSS Ismay created stylelint-config-styled-components-processor. It sets up a concise set of defaults, the bare minimum specific to styled-components. For all the other choices, use your favorite stylelint config like you always have!

Full TypeScript support

Our default JavaScript parser, Babylon (the one used in Babel), can only parse vanilla JavaScript or Flow, which means the processor didn’t have any TypeScript support at all. We’re not the only ones with this problem. eslint, the JavaScript linter, also wanted to support TS but couldn’t with their existing parser — so they created eslint-typescript-parser.

The processor now detects .ts (or .tsx) files and uses the ESLint TypeScript parser; you can now get the full goodness of linting your styled components together with the full goodness of statically typed JavaScript!

There’s a lot more in this and some previous releases that we’re very excited about, check out the full changelog for more. We also have lots of plans for the future, check out the issues in the repo to learn more!