babel-plugin-styled-components-css-namespace

Getting Started

1. Add the plugin with yarn add @quickbaseoss/babel-plugin-styled-components-css-namespace or npm install @quickbaseoss/babel-plugin-styled-components-css-namespace
2. Include the plugin in your babel configuration.

"babel": {
  "plugins": [
    "@quickbaseoss/babel-plugin-styled-components-css-namespace"
  ]
}

If you are also using babel-plugin-styled-components, you must place styled-components-css-namespace before styled-components.

"babel": {
  "plugins": [
    "@quickbaseoss/babel-plugin-styled-components-css-namespace",
    "styled-components"
  ]
}

Options

Default

Without adding options, this plugin will duplicate the class name generated by styled-components as suggested in this issue.

// output
.hzy34z.hzy34z {
  background-color: blue;
}

Simple Namespace

You can provide a cssNamespace to use instead of duplicating the class name. Remember to include a DOM element with that class that wraps the styled-component.

"babel": {
  "plugins": [
    ["@quickbaseoss/babel-plugin-styled-components-css-namespace", {"cssNamespace": "moreSpecific"}],
    "styled-components"
  ]
}

// output
.moreSpecific .hzy34z {
  background-color: blue;
}

Cascade Namespaces

You can provide an array cssNamespaces to use instead of duplicating the class name. Remember to include a DOM element with those classes that wraps the styled-component.

"babel": {
  "plugins": [
    ["@quickbaseoss/babel-plugin-styled-components-css-namespace", {
      "cssNamespace": ["moreSpecific", "reallySpecific", "extraSpecific"]
    }],
    "styled-components"
  ]
}

// output
.moreSpecific .reallySpecific .extraSpecific .hzy34z {
  background-color: blue;
}

Multiple Namespaces

The plugin contains an option to define an alternative strategy to apply the css namespace. This behaviour allow developers to define what type of namespace. Currently, if one or more namespaces are added to cssNamespace the items are transformed into classes and join them. e.g.

cssNamespace: ["body", "something"];

This will generate the rule .body .something & { ... } as namespace if you don't have a self reference in your component.

Using the alternative strategy allow defining the type of namespace wished and, also, allow multiple namespaces. e.g.

rawCssNamespace: ["body #rootElementId .specificClass", "#altRootElement"];

This will generate this rule for a component that does not start with a self-reference.

body #rootElementId .specificClass,
#altRootElement {
  & {
    /* css styled block here */
  }
}

But, it would generate the following rule for a component that starts with a self-reference.

body #rootElementId .specificClass,
#altRootElement {
  /* css styled block here */
}

Note I: The key rawCssNamespace should replace the cssNamespace. If both exists at the same level, the cssNamespace takes precedence.

Using the rawCssNamespace correctly e.g.

"babel": {
  "plugins": [
    ["@quickbaseoss/babel-plugin-styled-components-css-namespace", {
      "rawCssNamespace": [
        "body #rootElementId .specificClass",
        "#altRootElement"
      ]
    }],
    "styled-components"
  ]
}

Note II: This new alternative strategy is supposed to solve the issue below. It is intend to be experimental at the moment, then, after getting community feedback it might become official.

Known Issues

The plugin currently has fairly simple logic for applying a more specific selector. While this covers most use cases, you may see issues if you use sibling or child selectors with &. For example, & + & or .invalid & will place the more specific selector in the wrong place.

QuickBase#12

The Problem

styled-components is an awesome library for css-in-js and feels like a natural combination of React and CSS. It is easy to use and produces css instead of inline styles.

However, if you are trying to gradually introduce styled-components into a legacy website that might not have the best CSS, the legacy styles may bleed into your styled-components because they have more specificity than the single class styled-components.

The Solution

This plugin will automatically add additional css namespaces or duplicated classes to the selectors produced by styled components effectively creating a wall between the legacy css code and your new shiny styled components.

Styling frameworks

This plugin was built for Styled Components; however, since initially creating it, we at Quick Base have switched to Emotion. It works as an alternative to the stylis extra scope plugin which requires creating your own instance of stylis.

Developing

1. Clone the repo with git clone https://github.com/QuickBase/babel-plugin-styled-components-css-namespace.git
2. yarn install (prefer yarn although npm should work as well)
3. yarn test to run the tests

Publishing

When we are ready to release a new version, one of the admins needs to run the following commands to publish the new version to npm. We probably need to invest in a better deploy and semver management system. Interested? See this issue.

• If needed, open a new PR to update the version in the package.json
• Copy the commit hash from the commit log
• Run git tag -a {version} {commit_hash}. For example: git tag -a 0.0.9 abf3123
• In the editor, add a message about the changes in this version and save
• Push the tag to GitHub with git push --follow-tags
• Travis CI will build and publish the new version to npm