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({
            //
        }),
    ],
};

Installation

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'),
        // ...
    ],
};

Options

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

Name	Type	Default	Description
screens	object|boolean|undefined	undefined	Options for the Screens plugin. If false, disables the plugin.
outlines	object|boolean|undefined	undefined	Options for the Outlines plugin. If false, disables the plugin.

Helpers

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.

Screens

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.

Usage

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.

Options

Name	Type	Default	Description
enabled	boolean	!process?.env?.NODE_ENV?.startsWith('prod')	Determines whether the plugin should be executed or not.
ignore	string[]	['dark']	Set screens to be ignored. Ex.: "md".
selector	string	'body'	A valid CSS selector to which the plugin will style it's ::before pseudo-class.
label	string	'{key} ({value})'	The text that will populate the content: ''; of the pseudo-class. Two placeholders are available: key which will be replaced by the screen name (ex.: sm, md, ...) and value which will be replaced by the screen value (ex.: 640px, 768px, ...).
position	['bottom' | 'top', 'left' | 'right']	['bottom', 'left']	Specifies where the box should be positioned. The first item of the array should be either top or bottom and the second either left or right.

Styles customization

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.

Outlines

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.

Usage

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.

Options

Name	Type	Default	Description
enabled	boolean	!process?.env?.NODE_ENV?.startsWith('prod')	Determines whether the plugin should be executed or not.
selector	string	'.debug'	A valid CSS selector on which the plugin will apply styles to all the descendant children.

Styles customization

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

Display type	Hue range
block	{ min: 0, max: 59 } (red - orange)
inline-block	{ min: 180, max: 239 } (cyan - blue)
inline	{ min: 70, max: 120 } (yellow - green)
tables (table-caption, table-cell, ...)	{ min: 270, max: 299 } (purple - magenta)
others	{ min: 320, max: 330 } (magenta'ish - pink'ish)

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

Contributing

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

License

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