A set of debugging helpers for any TailwindCSS project

This plugin provides you with convenient debugging helpers to use in development. Here's a quick example:

// tailwind.config.js

module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('@vicgutt/tailwindcss-debug')({
            screens: {
                //
            },
            outlines: {
                //
            },
        }),

        // Or

        require('@vicgutt/tailwindcss-debug').screens({
            //
        }),
        require('@vicgutt/tailwindcss-debug').outlines({
            //
        }),
    ],
};

Install the plugin via NPM (or yarn):

# Using npm
npm i @vicgutt/tailwindcss-debug

# Using Yarn
yarn add @vicgutt/tailwindcss-debug

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js

module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('@vicgutt/tailwindcss-debug'),
        // ...
    ],
};

The plugin exposes a few options that may be used to configure the plugin's behaviour.

The wrapper plugin exposes two underlying plugins: screens & outlines. Each of them may be enabled, disabled, or have their behaviour customized by providing the corresponding plugin option (see above). All resulting CSS styles from those plugins will be added to the components layer.

The Screens plugin is heavily inspired by tailwindcss-debug-screens and all credits goes to @jorenvanhee. I decided to replicate the feature simply to have better defaults that suits me out of the box.

This plugin adds a small box at the bottom left (configurable) corner of your screen showing you the currently active responsive breakpoint. Here's a demo of what it does: https://play.tailwindcss.com/zVpiGgmWbt?file=config.

Require the plugin in your Tailwing config:

module.exports = {
    theme: {
        // ...
        debug: {
            screens: {
                // ...
            },
        },
    },
    plugins: [
        require('@vicgutt/tailwindcss-debug')({
            screens: {
                //
            },
        }),

        // Or (same as above)

        require('@vicgutt/tailwindcss-debug').screens({
            //
        }),
    ],
};

By default it will style the ::before pseudo-class of the body of the page.

To customize the CSS styles of the box, add a debug.screens object to your Tailwind theme. Ex.:

{
    theme: {
        // ...
        debug: {
            screens: {
                fontSize: '2rem',
                backgroundColor: '#000',
                // ...
            },
        },
    },
};

Please refer to the src/plugins/screens.ts file to see all the default styles.

The idea of the Outlines plugin came from studiometa's debug-outline plugin so a big thank you to @studiometa.

This plugin allows you to visualise your HTML structure by adding colored outlines to elements present in the DOM. Here's a demo of what it does: https://play.tailwindcss.com/Hcdj19LvjL?file=config.

Require the plugin in your Tailwing config:

module.exports = {
    theme: {
        // ...
        debug: {
            outlines: {
                // ...
            },
        },
    },
    plugins: [
        require('@vicgutt/tailwindcss-debug')({
            outlines: {
                //
            },
        }),

        // Or (same as above)

        require('@vicgutt/tailwindcss-debug').outlines({
            //
        }),
    ],
};

Then add the debug (configurable) class to any HTML element you'd like to debug.

To customize the CSS styles of any element, add a debug.outlines object to your Tailwind theme. Ex.:

{
    theme: {
        // ...
        debug: {
            outlines: {
                h1: {
                    outline: `1px solid hsla(23.91, 100%, 50%, 0.5) !important`,
                },
                // ...
            },
        },
    },
};

Outline colors per HTML tag's display type

Please refer to the src/plugins/outlines.ts file to see how the default styles are generated.

If you're interested in contributing to the project, please read our contributing docs before submitting a pull request.

The MIT License (MIT). Please see License File for more information.