{"id":15365925,"url":"https://github.com/andywer/postcss-theme","last_synced_at":"2025-04-15T01:42:26.991Z","repository":{"id":57328582,"uuid":"55796254","full_name":"andywer/postcss-theme","owner":"andywer","description":"PostCSS plugin to enable versatile theming.","archived":false,"fork":false,"pushed_at":"2016-04-22T09:54:45.000Z","size":18,"stargazers_count":87,"open_issues_count":5,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T13:43:57.439Z","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/andywer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-08T17:10:01.000Z","updated_at":"2023-09-08T17:09:00.000Z","dependencies_parsed_at":"2022-09-21T01:52:16.118Z","dependency_job_id":null,"html_url":"https://github.com/andywer/postcss-theme","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpostcss-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpostcss-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpostcss-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpostcss-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andywer","download_url":"https://codeload.github.com/andywer/postcss-theme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813698,"owners_count":21165629,"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-10-01T13:16:43.268Z","updated_at":"2025-04-15T01:42:26.974Z","avatar_url":"https://github.com/andywer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postcss-theme - Proper theming for PostCSS\n[![Build Status](https://travis-ci.org/andywer/postcss-theme.svg?branch=master)](https://travis-ci.org/andywer/postcss-theme)\n[![NPM Version](https://img.shields.io/npm/v/postcss-theme.svg)](https://www.npmjs.com/package/postcss-theme)\n\nSuper lightweight, straight-forward and written with performance in mind.\nCan be used with Webpack, JSPM/System.js or anywhere else where you use\nPostCSS!\n\n## What is it able to do?\n\nYou have a user interface and a bunch of CSS files / fancy CSS modules\nto style it. You want to be able to customize this styling. Let's say you have\nthis CSS file:\n\n```css\n/* header.css */\n\n@value black, white from '../theme/colors.css';\n\n.header {\n  composes: menu from '../theme/menu.css';\n  background: black;\n  color: white;\n}\n\n\n/* ../theme/colors.css */\n\n@value black: #303030;\n@value white: #F8F8F8;\n\n\n/* ../theme/components/menu.css */\n\n.menu {\n  box-shadow: 2px 2px 5px;\n}\n```\n\nWe are using the [postcss-modules-values](https://github.com/css-modules/postcss-modules-values)\nplugin here, so we can declare variables and import variables from other files\nusing `@value`.\nAnd we use [postcss-modules-extract-imports](https://github.com/css-modules/postcss-modules-extract-imports)\nso we can merge classes from different files into the current class using\n`composes: some-other-class from './other-file.css'`.\n\n*But you want to be able to change the styling!* You could just overwrite all these\nstyle rules with your own ones, but that is a lot of work and you must adapt it\neverytime these rules change.\n\nSo we use **postcss-theme** and do this:\n\n```css\n/* header.css */\n\n/* `theme(colors)` will be re-written to `\"./path/to/theme/colors.css\"` */\n@value black, white from theme(colors);\n\n.header {\n  /* will be resolved to the file path, too */\n  composes: menu from theme(components/menu);\n  background: black;\n  color: white;\n}\n```\n\nWhen configuring the PostCSS plugins in your webpack config or JSPM CSS loader:\n\n```javascript\nimport themePlugin from 'postcss-theme'\n\n/* postcss plugins: */\n[\n  themePlugin({ themePath: './path/to/theme-folder' }),\n  /* all other plugins go here */\n]\n```\n\nTa-da! You are now able to specify the path to the directory containing your\ntheme's CSS files during your build process. Just change it to a directory\ncontaining another theme if you want to change the styling.\n\n\n## Installation\n\n```bash\nnpm install postcss-theme --save\n```\n\n## Usage\n\nJust add this plugin to your array of PostCSS plugins and pass it an options\nobject like `{ themePath: './path/to/theme-folder' }`.\n\n### Webpack\n\nIn your webpack config:\n\n```javascript\nimport theme from 'postcss-theme'\n\nmodule.exports = {\n  module: {\n    loaders: [\n      {\n        test:   /\\.css$/,\n        loader: 'style-loader!css-loader!postcss-loader'\n      }\n    ]\n  },\n  postcss: function () {\n    return [\n      theme({ themePath: './path/to/theme' }),\n      // all other postcss plugins go here\n    ]\n  }\n}\n```\n\n### JSPM (jspm-loader-css)\n\nIn your css loader file (`css.js`):\n\n```javascript\nimport { CSSLoader, Plugins } from 'jspm-loader-css'\nimport theme from 'postcss-theme'\n\nconst { fetch, bundle } = new CSSLoader([\n  theme({ themePath: './path/to/theme' }),\n  Plugins.localByDefault,\n  Plugins.extractImports,\n  Plugins.scope,\n  Plugins.values,\n  // or any other postcss plugins\n], __moduleName)\n\nexport { fetch, bundle }\n```\n\n### Vanilla postcss call\n\n```javascript\nimport postcss from 'postcss'\nimport autoprefixer from 'autoprefixer'\nimport extractImports from 'postcss-modules-extract-imports'\n// ...\nimport theme from 'postcss-theme'\n\npostcss([\n  theme({\n    themePath: './path/to/theme'\n  }),\n  extractImports,\n  autoprefixer,\n  // or whatever plugins you would like to use\n]).process(/* ... */)\n```\n\n\n## Changelog\n\n### Version 1.1.1\n\nPass `css.source` to custom file path resolvers.\n\n### Version 1.1.0\n\nAllow passing a custom file path resolver function (`options.themeFileResolver`).\n\n### Version 1.0.1\n\nWindows fix. See [this issue](https://github.com/andywer/postcss-theme/issues/1).\n\n### Version 1.0.0\n\nInitial release.\n\n\n## License\n\nThis plugin is released under the terms of the MIT license. See [LICENSE](https://github.com/andywer/postcss-theme/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpostcss-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandywer%2Fpostcss-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpostcss-theme/lists"}