{"id":13397776,"url":"https://github.com/uncss/grunt-uncss","last_synced_at":"2025-05-14T03:09:44.796Z","repository":{"id":10604813,"uuid":"12821113","full_name":"uncss/grunt-uncss","owner":"uncss","description":":scissors: A grunt task for removing unused CSS from your projects.","archived":false,"fork":false,"pushed_at":"2023-07-18T21:07:56.000Z","size":1592,"stargazers_count":3818,"open_issues_count":9,"forks_count":173,"subscribers_count":99,"default_branch":"main","last_synced_at":"2025-04-13T20:17:49.491Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","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/uncss.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-09-13T22:56:45.000Z","updated_at":"2025-04-13T09:23:35.000Z","dependencies_parsed_at":"2024-06-18T12:30:14.765Z","dependency_job_id":"4aa8b116-3021-4b0d-8b71-563859acd187","html_url":"https://github.com/uncss/grunt-uncss","commit_stats":{"total_commits":334,"total_committers":23,"mean_commits":"14.521739130434783","dds":0.5239520958083832,"last_synced_commit":"6328d7ad9a980907e320f56d67e228d55085adf6"},"previous_names":["addyosmani/grunt-uncss"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uncss%2Fgrunt-uncss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uncss%2Fgrunt-uncss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uncss%2Fgrunt-uncss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uncss%2Fgrunt-uncss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uncss","download_url":"https://codeload.github.com/uncss/grunt-uncss/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059510,"owners_count":22007769,"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-07-30T18:01:44.335Z","updated_at":"2025-05-14T03:09:44.770Z","avatar_url":"https://github.com/uncss.png","language":"HTML","funding_links":[],"categories":["HTML","Minifiers","📦 Legacy \u0026 Inactive Projects"],"sub_categories":["Meetups"],"readme":"# grunt-uncss\n\n[![Built with Grunt](https://gruntjs.com/cdn/builtwith.svg)](https://gruntjs.com/) [![Build Status](https://github.com/uncss/grunt-uncss/workflows/Tests/badge.svg)](https://github.com/uncss/grunt-uncss/actions?workflow=Tests)\n\n\u003eA grunt task for removing unused CSS from your projects with [UnCSS](https://github.com/uncss/uncss).\n\n## Getting Started\n\nIf you haven't used [Grunt](https://gruntjs.com/) before, be sure to check out the\n[Getting Started](https://gruntjs.com/getting-started) guide, as it explains how to create\na [Gruntfile](https://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins.\nOnce you're familiar with that process, you may install this plugin with this command:\n\n```shell\nnpm install grunt-uncss --save-dev\n```\n\nOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:\n\n```js\ngrunt.loadNpmTasks('grunt-uncss');\n```\n\n**Issues with the output should be reported on the UnCSS [issue tracker](https://github.com/uncss/uncss/issues).**\n\n## Preview\n\nTaking a multi-page project using Bootstrap with \u003e120KB of CSS down to 11KB.\n\n![Demo](https://i.imgur.com/uhWMALH.gif)\n\n## Uncss task\n\n*Run this task with the `grunt uncss` command.*\n\nTask targets, files and options may be specified according to the grunt [Configuring tasks](https://gruntjs.com/configuring-tasks) guide.\n\n## Options\n\nOptions are passed to [UnCSS](https://github.com/uncss/uncss#within-nodejs). In addition this task defines an extra option:\n\n### report\n\n* Choices: `'min'`, `'gzip'`\n* Default: `'min'`\n\nReport minification result or both minification and gzip results.\nThis is useful to see exactly how well clean-css is performing but using `'gzip'` will make the task take 5-10x longer to complete. [Example output](https://github.com/sindresorhus/maxmin#readme).\n\n## Usage examples\n\nUse the `grunt-uncss` task by specifying a target destination (file) for your cleaned CSS.\nBelow this is `dist/css/tidy.css`.\n\nAlong-side, specify the input HTML files you would like scanned for used selectors.\nIn this case `app/index.html` and `app/about.html` are the two files we would like checked.\n\n```js\nuncss: {\n    dist: {\n        files: {\n            'dist/css/tidy.css': ['app/index.html', 'app/about.html']\n        }\n    }\n}\n```\n\nWhich you can then use alongside a processor like\n[processhtml](https://github.com/dciccale/grunt-processhtml) to\nrewrite the location of your stylesheet to `tidy.css` using a block like:\n\n```html\n\u003c!-- build:css css/tidy.css --\u003e\n\u003clink rel=\"stylesheet\" href=\"css/normalize.css\"\u003e\n\u003clink rel=\"stylesheet\" href=\"css/main.css\"\u003e\n\u003clink rel=\"stylesheet\" href=\"css/bootstrap.css\"\u003e\n\u003c!-- /build --\u003e\n```\n\nand some configuration like:\n\n```js\nprocesshtml: {\n    dist: {\n        files: {\n            'dist/index.html': ['app/index.html'],\n            'dist/about.html': ['app/about.html']\n        }\n    }\n}\n```\n\n```js\n// Remove unused CSS across multiple files\nuncss: {\n    dist: {\n        files: {\n            'dist/css/tidy.css': ['app/index.html', 'app/about.html']\n        }\n    }\n}\n```\n\n```js\n// Remove unused CSS across multiple files and ignore specific selectors\nuncss: {\n    dist: {\n        options: {\n            ignore: ['#added_at_runtime', '.created_by_jQuery']\n        },\n        files: {\n            'dist/css/tidy.css': ['app/index.html', 'app/about.html']\n        }\n    }\n}\n```\n\n```js\n// Remove unused CSS from URLs (php, node, etc.)\n// (Note that`nonull` must be true, or else Grunt\n// removes remote paths that it can't find locally)\nuncss: {\n    dist: {\n        files: [{\n            nonull: true,\n            src: ['http://localhost:8080/path1', 'http://localhost:8080/path2'],\n            dest: 'dist/css/tidy.css'\n        }]\n    }\n}\n```\n\n## Examples\n\n### Sites\n\n* [HTML5Boilerplate.com website](https://github.com/h5bp/html5boilerplate.com)\n* [Mozilla's DXR documentation viewer](https://github.com/mozilla/dxr)\n* [Vanilla forums docs site](https://github.com/vanilla/vanilla-docs)\n\n### Apps\n\n* [GitHub Team Viewer - Angular app](https://github.com/vinitkumar/github-team-viewer)\n* [Angular Todo application](https://github.com/JeremyCarlsten/grunt-uncss-angular-example)\n* [CashSplitter - Angular app with PouchDB, Bootstrap](https://github.com/carlo-colombo/CashSplitter)\n* [This Week's Comics Express app](https://github.com/WillsonSmith/thisWeeksComics)\n* [Sample grunt-uncss in a Sass project](https://github.com/uncss/grunt-uncss-sass-example)\n\n### Other\n\n* [Using grunt-uncss with Wordpress](https://github.com/sboodhoo/Grunt-UnCSS-WordPress)\n* [JSON Sitemap generator for grunt-uncss](https://github.com/phoenixMag00/JSON-Sitemap-Generator-for-Grunt-UnCSS-with-WordPress)\n\n## The problem\n\nUser-interface libraries like [Bootstrap](https://getbootstrap.com), [TopCoat](http://topcoat.io)\nand so on are fairly prolific, however many developers use less than 10% of the CSS they provide\n(when opting for the full build, which most do). As a result, they can end up with fairly bloated\nstylesheets which can significantly increase page load time and affect performance.\n`grunt-uncss` is an attempt to help with by generating a CSS file containing only the CSS used\nin your project, based on selector testing.\n\n## Research and alternative solutions\n\nThere have been many efforts to try solving the problem of finding unused CSS in the past. Opera created\n[ucss](https://github.com/oyvindeh/ucss), @aanand created \u003chttps://github.com/aanand/deadweight\u003e,\nBrian Le Roux [CSS Slap Chop](https://github.com/brianleroux/css-slap-chop) and there were a number of\nclient-side solutions also crafted, such as [Helium-CSS](https://github.com/geuis/helium-css),\n[CSSESS](https://github.com/driverdan/cssess) and the Python [mincss](https://www.peterbe.com/plog/mincss).\n\nUnfortunately, most of these solutions don't actually generate what you're really after - a leaner build\nof your project CSS containing only those rules you used. Finding that a more recent project called\n[UnCSS](https://github.com/uncss/uncss) did try tackling this, I set out to share some of the problems we\nneed to solve in this space with the developer and build a Grunt task to enable usage of it in builds more\neasily.\n\nHuge thanks go out to Giacomo Martino for his help with the Node module this task uses.\n\n## Coverage\n\n* [Spring-cleaning unused CSS with Grunt, Gulp \u0026 other build systems](https://addyosmani.com/blog/removing-unused-css/)\n* [Automating the removal of unused CSS - VelocityConf](https://www.youtube.com/watch?v=833xr1MyE30)\n* [Foundation 5, Sass and Grunt UnCSS](https://corydowdy.com/blog/foundation-5-sass-and-grunt-uncss)\n* [Automating Front-end Workflow (slides)](https://speakerdeck.com/addyosmani/automating-front-end-workflow)\n* [Automatically removing unused CSS - Windows](http://deanhume.com/automatically-removing-unused-css-using-grunt/)\n* [Workflow for responsive email with Grunt and UnCSS](https://medium.com/p/32d607879082)\n\n## WordPress\n\nWhile UnCSS works best (and quickest) with static HTML files, it is possible to pass in\na URL array that contains all the URLs on your website, and process all used selectors that way.\n[@lgladdy](https://github.com/lgladdy) wrote a guide on how to do this\n[on his blog](https://gladdy.uk/blog/2014/04/13/using-uncss-and-grunt-uncss-with-wordpress/)\n\n## Yeoman Generator\n\nIf you're looking for a webapp starting point with grunt-uncss integrated, see [generator-webapp-uncss](https://github.com/addyosmani/generator-webapp-uncss).\n\n## Limitations\n\nPlease note that the CSS parser used in the `uncss` module we rely on currently isn't able to work with complex selectors.\nFor example `[data-section=''] \u003e section \u003e [data-section-title] a`. This may mean that at build time you run into exceptions\nsuch as `TypeError: Cannot convert undefined or null to object`. If this is the case, please consider moving these selectors\nto a separate stylesheet which the task does not run on.\n\nWe are actively looking at how to improve the CSS parsers used and will update this notice once this problem has been solved.\n\n## Maintainers\n\n* [@addyosmani](https://github.com/addyosmani)\n* [@XhmikosR](https://github.com/XhmikosR)\n\n## License\n\n(C) Addy Osmani 2020, released under the MIT license\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funcss%2Fgrunt-uncss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funcss%2Fgrunt-uncss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funcss%2Fgrunt-uncss/lists"}