PHP Classes

How Can PHP Find Unused CSS Styles From Twig or Vue.js Template Files Using the Tool Unused CSS Finder: Find unused styles from CSS and SASS files

Recommend this page to a friend!
     
  Info   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2024-09-29 (11 days ago) RSS 2.0 feedNot enough user ratingsTotal: 37 This week: 5All time: 10,956 This week: 9Up
Version License PHP version Categories
unused-css-finder 1.0.0MIT/X Consortium ...7.4Tools, Templates, Console, Performanc..., P..., P...
Description 

Author

This package can find unused styles from CSS and SASS files.

It provides a tool in the form of a PHP script that can run from the command line console to scan files or directories with CSS files or SASS files (.scss) to find styles unused in template files in the Twig or Vue.js formats.

The tool lists the unused CSS styles or mentions that it did not find any unused styles.

Innovation Award
PHP Programming Innovation award nominee
September 2024
Nominee
Vote
One way to make pages load faster is to optimize CSS stylesheets by removing CSS styles not used on the current page.

Nowadays many PHP projects use the Twig or the Vue.js template format to define the output of pages.

This package can scan template files in those formats to find unnecessary CSS styles and make the pages load faster if the developer decides to remove those styles.

Manuel Lemos
Picture of Engin Ypsilon
Name: Engin Ypsilon <contact>
Classes: 6 packages by
Country: Germany Germany
Age: 44
All time rank: 4117220 in Germany Germany
Week rank: 9 Up1 in Germany Germany Up
Innovation award
Innovation award
Nominee: 2x

Details

Unused CSS Finder for Twig or Vue Projects

Authors: ChatGPT by OpenAI & Engin Ypsilon by classic::Parents()

Overview

UnusedCssFinder is a lightweight PHP-based tool designed to help developers clean up unused CSS classes in projects that use Vue.js, Twig, or similar templating systems. By scanning both the CSS and component files, this tool identifies CSS selectors that are defined but not used, making it easier to reduce file size, optimize performance, and maintain clean code.

It's an efficient, no-frills solution that doesn't require additional dependencies or frameworks, ideal for quickly assessing unused CSS without heavy setup.

Features

  • Recursively fetches and reads all CSS classes from `.css` or `.scss` files. - Note: This tool currently supports `.css` and `.scss` files. `.sass` files are not fully supported due to differences in syntax.
  • Scans `.vue`, `.js`, and `.twig` files to detect unused CSS classes.
  • Outputs a list of CSS classes that are not used in your project, which can likely be removed.
  • Allows custom configuration, including ignored selectors and files.
  • Optional extended mode for more detailed output, including scanned files and class details.

Requirements

  • PHP 7.4 or higher
  • A project containing Vue.js, Twig, or similar component-based files (`.vue`, `.js`, or `.twig`)
  • CSS/SCSS files with class definitions

Installation

  • Clone the repository:
git clone https://github.com/eypsilon/unused-css-finder.git
cd unused-css-finder

  • Make the script executable:
chmod +x find-unused-css.php

__Usage__

To use the script, run the following command in your terminal:

# The more precise the directories are set,
# the more accurate results you will get.
./find-unused-css.php <path/to/css> <path/to/components>

__Example:__

./find-unused-css.php ./src/assets ./src/components

The tool will output a list of unused CSS classes or a message indicating that no unused classes were found.

Optional Config

You can specify additional configurations by passing parameters such as ignored selectors or files:

# available
$config = [
    'extendedMode'    => (string) 'false',                // if 'true' returns the lists of scanned files and a list with all found selectors
    'outputMode'      => null,                            // set to "json" to get the resulting response as JSON Object, `unusedOnly` for a valid JSON response
    'ignoreSelectors' => ['mt-button', 'some-box-class'], // example of ignored selectors
    'ignoreFiles'     => ['/path/to/ignore/file.vue'],    // example of ignored files
];

Set an Alias (Optional)

For convenience, you can create an alias to run the tool easily:

  1. Open `.bash_aliases`:
sudo nano ~/.bash_aliases

  1. Add the following alias:
alias GetUnusedCss='~/unused-css-finder/find-unused-css.php'

  1. Refresh your aliases:
source ~/.bash_aliases

Now you can use the alias to run the script:

GetUnusedCss <path/to/css> <path/to/components>

To use with optional configurations:

GetUnusedCss <path/to/css> <path/to/components> extendedMode='true' outputMode='json' ignoreSelectors='mt-button,some-box-class' ignoreFiles='/path/to/ignore/file.vue'

Configuration file

Instead of passing the configuration options via arguments in the terminal, you can also create a JSON configuration file with all the necessary data for your project. This makes it easy to manage and reuse different configurations for multiple projects or environments. The filename needs to end with 'unused_css.json'.

__Example Configuration__

{
    "cssDir": "/path/to/css",         // The directory where your CSS files are located
    "srcDir": "/path/to/components",  // The directory where your Vue components are located
    "extendedMode": "true",           // If true, provides additional details on searched files and CSS files
    "outputMode": "json",             // ['json','unusedOnly'] Specify output format ('json' or plain text)
    "ignoreSelectors": [],            // A list of CSS selectors to ignore during the search (e.g., framework-specific classes)
    "ignoreFiles": [],                // A list of specific files to exclude from the search
    "extensions": {
        "css": [
            "css",
            "scss"
        ], // Supported file extensions for CSS; .sass files are not fully supported due to differences in syntax.
        "source": [
            "vue",
            "js",
            "twig"
        ] // Supported file extensions for source files (Vue, JS, Twig, etc.)
    }
}

__Using the Configuration File__

Once you've created the configuration file, you can pass it as an argument when running the script. The script will use the settings defined in the JSON file instead of arguments passed directly in the terminal.

__Example Command:__

# Using an alias
GetUnusedCss /path/to/config/unused_css.json

# Without an alias, using the script directly
./find-unused-css.php /path/to/config/unused_css.json

__Configuration Options Explained__

  • `cssDir`: The directory where your CSS/SCSS files are stored. The script will recursively search this directory for all files with the extensions defined in the `extensions` ? `css` field.
  • `srcDir`: The directory where your Vue, JS, or Twig component files are stored. This is where the script will search for CSS class usage.
  • `extendedMode`: When set to `true`, the script will output additional details about the files it has scanned, including the CSS selectors and source files. This can be helpful for debugging or tracking what files were included in the search.
  • `outputMode`: Defines how the output will be displayed. Set it to `'json'` for structured JSON output, which is easier to integrate into automated systems or use `'plain'` for a standard text output. If you only want a list with unused selectors in a JSON array, set `'unusedOnly'`.
  • `ignoreSelectors`: This is a list of CSS selectors that should be excluded from the search. For example, if you're using a UI framework like Bootstrap or Tailwind, you may want to exclude some of its global classes (e.g., `btn-primary`, `text-lg`) from the search to avoid false positives.
  • `ignoreFiles`: A list of specific files that should be skipped during the search. You can use this to exclude generated files, temporary files, or any files that you don't want the script to analyze.
  • `extensions`: - `css`: Specifies which CSS-related file extensions the script should look for in the `cssDir`. Typically includes `css` and `scss`. - `source`: Specifies which file extensions the script should search in the `srcDir` for class usage. This typically includes `vue`, `js`, and `twig` but can be extended to other formats like `html`.

__Examples__

Example 1: Basic Usage with Arguments

./find-unused-css.php ./src/assets ./src/components

Example 2: Advanced Usage with Configuration File

GetUnusedCss ./src/unused_css.json

Example 3: Ignoring Selectors and Files

{
    "cssDir": "/path/to/css",
    "srcDir": "/path/to/components",
    "extendedMode": "false",
    "outputMode": "plain",
    "ignoreSelectors": ["mt-button", "hidden"],
    "ignoreFiles": ["/path/to/components/temp.vue"],
    "extensions": {
        "css": [
            "css",
            "scss"
        ],
        "source": [
            "vue",
            "js",
            "twig"
        ]
    }
}

You can then run this configuration with:

./find-unused-css.php /path/to/config/unused_css.json

Disclaimer

Please note that this tool is a lightweight, approximately 200-line script designed to give a general overview of potentially unused CSS selectors in your projects. While it does a good job of finding most unused classes, it may miss certain scenarios, such as:

  • Dynamically generated class names (e.g., classes added via JavaScript, Vue mixins, or other logic).
  • Classes used in inline styles or within style attributes.
  • Classes generated by CSS frameworks or libraries where the class names are dynamically assembled (e.g., Tailwind CSS, Bootstrap with mixins).
  • Files not covered by the defined extensions (e.g., templates using another engine).

This tool is not a replacement for more comprehensive code quality solutions, but rather a fast and simple utility to help developers clean up unused CSS. It should be used in combination with manual review or other tools for more complex use cases.

Contribution

Feel free to submit issues or pull requests if you'd like to improve or extend this tool. Contributions are always welcome!

License

This project is licensed under the MIT License.


  Files folder image Files (5)  
File Role Description
Accessible without login Plain text file config.unused_css.json Data Auxiliary data
Plain text file find-unused-css.php Class Class source
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file test.example.scss Data Auxiliary data

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:37
This week:5
All time:10,956
This week:9Up