htmlnano

By default, htmlnano only performs safe transformations. You can customize which modules are active by passing an options object where the keys are the module names.

• To disable a specific module, pass false as its value.
• To enable a specific module, pass true as its value.

Important: The order in which you define modules in your configuration determines the order in which they are applied to your HTML. The modules are applied in the sequence they appear in the configuration object.

htmlnano processes HTML using an ordered set of modules, where each module handles a specific concern such as comments, whitespace, attributes, inline CSS, or inline JS. This modularity makes behavior predictable and easy to tune.

To use htmlnano effectively, follow this typical workflow:

1. Select a preset: Start with a baseline like safe, ampSafe, or max.
2. Customize: Override only the specific modules you need to adjust.
3. Execute: Run htmlnano as the final step in your PostHTML pipeline.

To use htmlnano in your project, install it using npm:

npm install htmlnano

To set up the development environment for the htmlnano-docs website, install the required dependencies using npm.

npm install

You can apply a preset by passing it as the third argument to htmlnano.process(). You can either access presets via the main htmlnano object or import them directly from their specific paths.

Using CommonJS:

const htmlnano = require('htmlnano');
const ampSafePreset = require('htmlnano').presets.ampSafe;

htmlnano.process(html, { collapseWhitespace: 'conservative' }, ampSafePreset)
    .then((result) => {
        // result.html is minified
    })
    .catch((err) => {
        console.error(err);
    });

Using ESM:

import htmlnano from 'htmlnano';
import ampSafe from 'htmlnano/presets/ampSafe';

const result = await htmlnano.process(html, {}, ampSafe);

By default, htmlnano walks up from process.cwd() to find a configuration file. This can be a security risk if running in untrusted directories, as executable config files (like .htmlnanorc.js) are require()d and run with your privileges.

To disable this implicit lookup:

• In the library: Set skipConfigLoading: true in the options object.
• In the CLI: Use the --no-config-search flag.

Note: Using --no-config-search in the CLI does not prevent you from loading a specific trusted file using -c or --config <file>.

# CLI
npx htmlnano test.html --no-config-search

Start a local development server to view the website. This command will automatically open a browser window and support live reloading, so most changes are reflected immediately without a server restart.

npm start

You can create your own presets by spreading an existing built-in preset into a new object and overriding or adding specific module configurations.

const htmlnano = require('htmlnano');
const emailPreset = {
    ...htmlnano.presets.safe,
    mergeStyles: true,
    minifyCss: {
        safe: true
    }
};

htmlnano.process(html, { removeComments: false }, emailPreset)
    .then((result) => {
        // result.html is minified
    })
    .catch((err) => {
        console.error(err);
    });

To define your own configuration from scratch without inheriting any preset settings, pass an empty object {} as the third argument to htmlnano.process().

const htmlnano = require('htmlnano');
const options = {
    // Your options
};

htmlnano
    .process(html, options, {})
    .then(function (result) {
        // result.html is minified
    })
    .catch(function (err) {
        console.error(err);
    });

You can pass an options object directly to htmlnano.process(). Options passed directly have the highest precedence and will override any values found in configuration files or presets.

htmlnano.process(html, {
    // options go here
});