{"id":29970797,"url":"https://github.com/fraktodev/frakto-postcss","last_synced_at":"2026-04-14T23:32:52.558Z","repository":{"id":305256342,"uuid":"1020567850","full_name":"fraktodev/frakto-postcss","owner":"fraktodev","description":"A PostCSS plugin that fragments, optimizes, and reconstructs your CSS the Frakto way.","archived":false,"fork":false,"pushed_at":"2025-08-06T03:59:15.000Z","size":157,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-25T22:53:08.216Z","etag":null,"topics":["css","optimize-css-files","postcss","postcss-plugin"],"latest_commit_sha":null,"homepage":"","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/fraktodev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T04:37:27.000Z","updated_at":"2025-08-01T21:19:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"c54ee039-3653-4888-af04-feed64a59c54","html_url":"https://github.com/fraktodev/frakto-postcss","commit_stats":null,"previous_names":["fraktodev/frakto-postcss"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fraktodev/frakto-postcss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraktodev%2Ffrakto-postcss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraktodev%2Ffrakto-postcss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraktodev%2Ffrakto-postcss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraktodev%2Ffrakto-postcss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraktodev","download_url":"https://codeload.github.com/fraktodev/frakto-postcss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraktodev%2Ffrakto-postcss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31819718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["css","optimize-css-files","postcss","postcss-plugin"],"created_at":"2025-08-04T06:00:59.625Z","updated_at":"2026-04-14T23:32:52.542Z","avatar_url":"https://github.com/fraktodev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://frakto.dev/\"\u003e\n    \u003cimg src=\"https://frakto.dev/dist/img/logos/frakto-iso.png\" alt=\"Bootstrap logo\" width=\"150\" height=\"173\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n\t\u003cstrong\u003eFrakto Postcss\u003c/strong\u003e\n  \u003cp\u003e\u003cem\u003eFragment. Optimize. Reconstruct.\u003c/em\u003e\u003c/p\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-1.0.0--beta-blue.svg\" alt=\"Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/npm-%5E10.0.0-blue.svg?logo=npm\u0026logoColor=white\" alt=\"npm\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PostCSS-%5E8.0.0-blue.svg?logo=postcss\u0026logoColor=white\" alt=\"PostCSS\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-brightgreen.svg\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/build-passing-brightgreen.svg\" alt=\"Build Status\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Prs-welcome-brightgreen.svg\" alt=\"Contributions welcome\"\u003e\n\u003c/div\u003e\n\n---\n\n# Frakto PostCSS\n\nA PostCSS plugin that brings sacred structure and visual clarity to your final CSS output.\n\nIt intelligently groups declarations into `@layer` blocks, reorders media queries for optimal performance, and ensures that your styles are both readable and scalable.\n\nMore than a formatter, it also features an integrated **purge engine** that removes unused styles from your CSS, reducing bundle size without breaking layout integrity — no external plugins required.\n\nOriginally designed to empower the **Frakto UI** framework, it's fully compatible with any modern CSS architecture or design system.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration Options](#configuration-options)\n- [Usage](#usage)\n- [Expected Output](#expected-output)\n- [Purge Mode](#purge-mode)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nYou can install Frakto PostCSS via your favorite package manager:\n\n```bash\nnpm install @frakto/postcss --save-dev\n```\n\nFrakto PostCSS is designed to work with PostCSS v8 or higher. Please make sure PostCSS is installed in your project.\n\n```bash\nnpm install postcss --save-dev\n```\n\n## Configuration Options\n\n`frakto-postcss` provides several configuration options to customize its behavior. You can pass them via plugin options or by creating a `frakto.config.mjs` file in your project root.\n\nIf a config file is present, inline plugin options will be ignored.\n\n### Available Options\n\n| Option             | Type               | Default     | Description                                                                                                                                                                                                |\n| ------------------ | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `purge`            | `boolean`          | `true`      | Enables purging of unused CSS classes and tags.                                                                                                                                                            |\n| `tagSafeList`      | `string[]`         | `[]`        | List of tag names to preserve during purging.                                                                                                                                                              |\n| `classSafeList`    | `string[]`         | `[]`        | List of class names to preserve during purging. Supports both literal strings and RegExp patterns. For example: `['btn-primary', /^m[trblxy]?-?\\d$/]` will preserve `.btn-primary`, `.mt-1`, `.mx-4`, etc. |\n| `includePaths`     | `string\\|string[]` | `'.'`       | Folders (relative to `process.cwd()`) to scan for source files.                                                                                                                                            |\n| `excludePaths`     | `string\\|string[]` | See below   | Folders to exclude during scanning.                                                                                                                                                                        |\n| `files`            | `string\\|string[]` | `['html']`  | File extensions (without dot) to include in the scan. Only the following extensions are valid: `html`, `astro`, `jsx`, `tsx`. Invalid ones will be ignored with a warning.                                 |\n| `orphansLayerName` | `string`           | `'orphans'` | Name of the layer used to group orphaned CSS rules.                                                                                                                                                        |\n| `layersOrder`      | `string[]`         | See below   | Custom order in which CSS layers will be printed.                                                                                                                                                          |\n\n#### Default `excludePaths`\n\n```js\n[\n  '.git',\n  '.tmp',\n  '.next',\n  '.cache',\n  '.turbo',\n  '.vercel',\n  '.vscode',\n  '.ds_store',\n  'tmp',\n  'test',\n  'tests',\n  'vendor',\n  'node_modules'\n];\n```\n\n#### Default `layersOrder`\n\n```js\n[\n  'theme',\n  'reset',\n  'base',\n  'layout.containers',\n  'layout.grid',\n  'layout.flex',\n  'layout.shortcuts',\n  'shortcuts',\n  'orphans'\n];\n```\n\nYou can override this order to suit your project's structure.\n\n## Usage\n\nFrakto PostCSS is a drop-in PostCSS plugin. Once installed and configured, you can integrate it into any PostCSS processing pipeline.\n\n### Basic Example (ESM)\n\n```js\nimport postcss from 'postcss';\nimport fraktoPostCSS from '@frakto/postcss';\n\nconst css = `/* your CSS content */`;\n\nconst result = await postcss([\n  fraktoPostCSS({\n    purge: true,\n    includePaths: 'src',\n    excludePaths: ['node_modules'],\n    files: ['html', 'astro']\n  })\n]).process(css);\n\nconsole.log(result.css);\n```\n\n### CommonJS Example\n\n```js\nconst postcss = require('postcss');\nconst fraktoPostCSS = require('@frakto/postcss');\n\nconst css = `/* your CSS content */`;\n\npostcss([\n  fraktoPostCSS({\n    purge: true,\n    includePaths: 'src',\n    excludePaths: ['node_modules'],\n    files: ['html', 'astro']\n  })\n])\n  .process(css)\n  .then((result) =\u003e {\n    console.log(result.css);\n  });\n```\n\n### Using frakto.config.mjs\n\nFrakto PostCSS can auto-load settings from a `frakto.config.mjs` file. When this file is present, options passed directly to the plugin will be ignored.\n\n```js\n// frakto.config.mjs\nexport default {\n  purge: true,\n  includePaths: ['src'],\n  excludePaths: ['node_modules'],\n  files: ['html', 'astro']\n};\n```\n\nThen in your PostCSS setup:\n\n#### Example: `postcss.config.mjs`\n\n```js\nimport fraktoPostCSS from '@frakto/postcss';\n\nexport default {\n  plugins: [fraktoPostCSS()]\n};\n```\n\nFor more control, see the [Configuration Options](#configuration-options) section.\n\n## Expected Output\n\nGiven the following input:\n\n```css\n@layer reset {\n  * {\n    margin: 0;\n    padding: 0;\n  }\n}\n\n@layer base {\n  h1 {\n    font-size: 2rem;\n  }\n}\n\n.btn {\n  padding: 1rem;\n  background: blue;\n}\n```\n\nAfter processing with `frakto-postcss`, the output will be:\n\n```css\n@layer reset, base, shortcuts;\n@layer reset {\n  * {\n    margin: 0;\n    padding: 0;\n  }\n}\n@layer base {\n  h1 {\n    font-size: 2rem;\n  }\n}\n@layer shortcuts {\n  .btn {\n    padding: 1rem;\n    background: blue;\n  }\n}\n```\n\nLayers are reordered, orphan rules are grouped under a dedicated layer, and formatting is normalized.\n\n## Purge Mode\n\nWhen `purge` is enabled in your configuration, Frakto PostCSS will analyze your source files (HTML, Astro, JSX, TSX) and remove any unused CSS selectors (tags and classes).\n\n### How it works:\n\n- Parses your files and extracts all HTML tags and values inside `class=\"...\"` attributes.\n- Then, it checks every layer (except `theme` and `reset`) and removes CSS rules that don't match any of the extracted tags or classes.\n\n### Safe lists:\n\nYou can define `tagSafeList` and `classSafeList` in your config to prevent specific selectors from being removed, even if they’re not found in your source files.\n\n### Example\n\n```js\nexport default {\n  purge: true,\n  tagSafeList: ['a', 'span', 'table'],\n  classSafeList: ['ghost', 'admin-only']\n};\n```\n\nThis helps you safely keep utility classes or elements added dynamically by JavaScript or frameworks.\n\n\u003e **Tip:** Use the safe lists to avoid removing styles for modals, dynamic components, or server-rendered templates.  \n\u003e If you're using Frakto UI, most dynamic components are already safe listed internally, so you typically won’t need to handle that manually.\n\n## Contributing\n\nContributions are welcome and encouraged.  \nIf you'd like to help improve this plugin, please open a pull request or issue.\n\nMake sure to follow our [contributing guidelines](https://github.com/fraktodev/frakto-postcss/blob/main/.github/CONTRIBUTING.md) before submitting any changes.\n\n## License\n\nMIT License — Copyright © 2025 [Frakto](https://github.com/fraktodev/)\n\n## Funding\n\nThis project is maintained with love and dedication.  \nIf you'd like to support its continued development, you can do so here:  \n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-%E2%98%95-yellow.svg?style=flat)](https://coff.ee/danybranding)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraktodev%2Ffrakto-postcss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraktodev%2Ffrakto-postcss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraktodev%2Ffrakto-postcss/lists"}