{"id":13708877,"url":"https://github.com/QuickBase/babel-plugin-styled-components-css-namespace","last_synced_at":"2025-05-06T15:31:21.927Z","repository":{"id":29860938,"uuid":"108360220","full_name":"QuickBase/babel-plugin-styled-components-css-namespace","owner":"QuickBase","description":"A babel plugin to add css namespaces (and increase specificity) of styled-component classes.","archived":false,"fork":false,"pushed_at":"2024-08-08T00:32:42.000Z","size":228,"stargazers_count":117,"open_issues_count":38,"forks_count":30,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-22T07:16:31.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QuickBase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-26T04:08:01.000Z","updated_at":"2025-01-24T05:44:24.000Z","dependencies_parsed_at":"2024-01-10T17:53:12.737Z","dependency_job_id":null,"html_url":"https://github.com/QuickBase/babel-plugin-styled-components-css-namespace","commit_stats":{"total_commits":58,"total_committers":14,"mean_commits":4.142857142857143,"dds":0.5862068965517242,"last_synced_commit":"22260001b8f85305370ddd435a4c26f7d52e99dc"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuickBase%2Fbabel-plugin-styled-components-css-namespace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuickBase%2Fbabel-plugin-styled-components-css-namespace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuickBase%2Fbabel-plugin-styled-components-css-namespace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuickBase%2Fbabel-plugin-styled-components-css-namespace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QuickBase","download_url":"https://codeload.github.com/QuickBase/babel-plugin-styled-components-css-namespace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252712892,"owners_count":21792386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T23:00:33.708Z","updated_at":"2025-05-06T15:31:21.422Z","avatar_url":"https://github.com/QuickBase.png","language":"JavaScript","readme":"# @quickbaseoss/babel-plugin-styled-components-css-namespace\n\n[![Travis CI status and link to builds](https://api.travis-ci.org/QuickBase/babel-plugin-styled-components-css-namespace.svg?branch=master)](https://travis-ci.org/github/QuickBase/babel-plugin-styled-components-css-namespace)\n\n## Getting Started\n\n1.  Add the plugin with `yarn add @quickbaseoss/babel-plugin-styled-components-css-namespace` or `npm install @quickbaseoss/babel-plugin-styled-components-css-namespace`\n1.  Include the plugin in your babel configuration.\n\n```json\n\"babel\": {\n  \"plugins\": [\n    \"@quickbaseoss/babel-plugin-styled-components-css-namespace\"\n  ]\n}\n```\n\nIf you are also using [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components), you must place `styled-components-css-namespace` **before** `babel-plugin-styled-components`.\n\n```json\n\"babel\": {\n  \"plugins\": [\n    \"@quickbaseoss/babel-plugin-styled-components-css-namespace\",\n    \"babel-plugin-styled-components\"\n  ]\n}\n```\n\n## Options\n\n### Default\n\nWithout adding options, this plugin will duplicate the class name generated by `styled-components` as suggested in [this issue](https://github.com/styled-components/styled-components/issues/613).\n\n```css\n/* output */\n.c0.c0 {\n  background-color: blue;\n}\n```\n\n### Increasing Specificity\n\nA common scenario when integrating styled-components into existing projects is fighting against extremely specific legacy CSS selectors such as `#someId .grossly .nested section input {/* styles */}`.\n\nTo increase the specificity that this plugin adds, you can leverage the [recommended approach from the styled-components docs](https://www.styled-components.com/docs/faqs#how-can-i-override-styles-with-higher-specificity). Add the appropriate number of `\u0026` selectors equal to the desired selector duplication as the `cssNamespace` option (the default behavior is x2 `{\"cssNamespace\": \"\u0026\u0026\"}`).\n\n```json\n{\n  \"plugins\": [\n    [\n      \"@quickbaseoss/babel-plugin-styled-components-css-namespace\",\n      {\"cssNamespace\": \"\u0026\u0026\u0026\"}\n    ],\n    \"babel-plugin-styled-components\"\n  ]\n}\n```\n\n```css\n/* output */\n.c0.c0.c0 {\n  background-color: blue;\n}\n```\n\n### Custom Namespace\n\nYou 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. The `cssNamespace` takes the form of the selector you want to use to wrap all of your styles with.\n\n```json\n\"babel\": {\n  \"plugins\": [\n    [\"@quickbaseoss/babel-plugin-styled-components-css-namespace\", {\"cssNamespace\": \".specific .moreSpecific .reallySpecific\"}],\n    \"styled-components\"\n  ]\n}\n```\n\n```css\n/* output */\n.specific .moreSpecific .reallySpecific .c0 {\n  background-color: blue;\n}\n```\n\n_where .c0 is the class added by styled-components to the element_\n\n## Notes\n\n### Media Query String Interpolation\n\nWhile an uncommon use-case, it can often be useful to interpolate media query at-rules in your css\ntemplate string. Compared to the [method for creating media queries from the\nstyled-component docs](https://www.styled-components.com/docs/advanced#media-templates), this\nmethod reduces the overhead of multiple calls of `css` while still allowing queries to be\nconstructed without requiring nested template literals.\n\n```javascript\nconst mediaQuery = '@media only screen and (min-width: 426px)'\n\nconst StyledComponent = styled.div`\n  background-color: red;\n  ${mediaQuery} {\n    background-color: blue;\n  }\n`\n```\n\nUnfortunately, this syntax is identical to the syntax used to refer to other components and this\nplugin cannot distinguish between the two and will produce broken CSS rules. Since referring to\nother components is more common, the below method of formatting `@media` inline can be\nused as a workaround.\n\n```javascript\nconst mediaQuery = 'only screen and (min-width: 426px)';\n\nconst StyledComponent = styled.div`\n  background-color: red;\n  @media ${mediaQuery} {\n    background-color: blue;\n  }\n`;\n```\n\n## Upgrade to version 1.0.0\n\nNote that `rawCssNamespace` was dropped in favor of the single `cssNamespace` option. Additionally, support for an array of selectors was dropped as well. Update any references to `rawCssNamespace` with `cssNamespace`.\n\nIf you were already using `cssNamespace`, update your configuration to use a css selector rather than an array of classes. E.g., `cssNamespace: 'moreSpecific'` should be `cssNamespace: '.moreSpecific'` and `cssNamespace: ['specific', 'verySpecific']` should be `cssNamespace: '.specific .verySpecific'`.\n\n## The Problem\n\n[styled-components](https://github.com/QuickBase/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.\n\nHowever, if you are trying to gradually introduce [styled-components](https://github.com/QuickBase/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.\n\n## The Solution\n\nThis 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.\n\n![monty-python-castle](https://media.giphy.com/media/12TIvbgMTrGhhu/giphy.gif)\n\n## Styling frameworks\n\nThis plugin was built for [Styled Components](https://www.styled-components.com/); however, since initially creating it, we at Quick Base have switched to [Emotion](https://emotion.sh/). It works as an alternative to the [stylis extra scope plugin](https://github.com/Andarist/stylis-plugin-extra-scope) which requires creating your own instance of stylis.\n\n## Developing\n\n1.  Clone the repo with `git clone https://github.com/QuickBase/babel-plugin-styled-components-css-namespace.git`\n1.  `yarn install` (prefer `yarn` although `npm` should work as well)\n1.  `yarn test` to run the tests\n\n## Publishing\n\nWhen 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.\nWe probably need to invest in a better deploy and semver management system. Interested? See [this issue](https://github.com/QuickBase/babel-plugin-styled-components-css-namespace/issues/9).\n\n- If needed, open a new PR to update the version in the [package.json](https://github.com/QuickBase/babel-plugin-styled-components-css-namespace/blob/master/package.json)\n- Copy the commit hash from the [commit log](https://github.com/QuickBase/babel-plugin-styled-components-css-namespace/commits/master)\n- Run `git tag -a {version} {commit_hash}`. For example: `git tag -a 0.0.9 abf3123`\n- In the editor, add a message about the changes in this version and save\n- Push the tag to GitHub with `git push --follow-tags`\n- Travis CI will build and publish the new version to npm\n\n## Acknowledgements\n\nOpen source software is a group effort. This version of the plugin was heavily inspired by [a fork](https://github.com/TrevorBurnham/babel-plugin-namespace-styled-components) of the original plugin from @TrevorBurnham.\n\nWe also would like to thank some of our contributors who helped solve some tough issues with the previous iteration of this plugin:\n\n- @daniloster\n- @dan-kez\n- @prevostc\n- @danielhusar\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuickBase%2Fbabel-plugin-styled-components-css-namespace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQuickBase%2Fbabel-plugin-styled-components-css-namespace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuickBase%2Fbabel-plugin-styled-components-css-namespace/lists"}