postcss-px-to-unit

An efficient PostCSS plugin for converting px units to relative length units (vw / vh / rem). This project has been refactored with performance optimizations, providing faster processing speed and more reliable conversion results.

Install

# npm
npm install postcss-px-to-unit -D

# yarn
yarn add postcss-px-to-unit -D

# pnpm
pnpm add postcss-px-to-unit -D

Usage

// webpack.config.js
import PxToUnit from 'postcss-px-to-unit';

...
{
  loader: 'postcss-loader',
  plugins: [
    PxToUnit({
      // options
    })
  ]
}
...

// vite.config.js
import PxToUnit from "postcss-px-to-unit";

export default defineConfig(() => ({
  // ...
  css: {
    postcss: {
      plugins: [
        PxToUnit({
          // options
        }),
      ],
    },
  },
  // ...
}));

Options

PxToUnit({
  targetUnit: "vw",
  ignoreThreshold: 1,
  viewportWidth: 375,
  viewportHeight: 667,
  htmlFontSize: 37.5,
  unitPrecision: 5,
  excludeFiles: [],
  excludeSelectors: [],
  excludeProperties: [],
  cacheSize: 100,
  debug: false,
});

| Option | Default | Description | | ----------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------- | | targetUnit | 'vw' | Target relative length unit. Support 'vw', 'vh', 'rem' and 'vw&rem' | | ignoreThreshold | 1 | px values less than or equal to this threshold won't be converted (compared by absolute value, so -10px is treated as 10px) | | viewportWidth | 375 | Base viewport width (for targetUnit: 'vw') | | viewportHeight | 667 | Base viewport height (for targetUnit: 'vh') | | htmlFontSize | 37.5 | Base html font-size (for targetUnit: 'rem') | | unitPrecision | 5 | Unit value precision | | excludeFiles | [] | Exclude file paths, supports regexp. (example: [/node_modules/]) | | excludeSelectors | [] | Exclude CSS selectors and their nested subtree, supports string and regexp. (example: ['.ignore']) | | excludeProperties | [] | Exclude CSS properties, supports string and regexp. (example: [/^width$/]) | | cacheSize | 100 | Max number of cached conversion results (LRU). Use Infinity for an unbounded cache, or 0 / a non-positive value to disable caching | | debug | false | Print debug logs of skipped/converted values |

Behavior notes

• Token-level value parsing. Values are parsed into tokens before conversion, so only real px dimensions are touched. px appearing inside strings, url(...), or CSS variable names is left untouched — e.g. width: var(--size-10px) stays var(--size-10px). Normal cases like calc(100% - 10px) are still converted.
• Invalid numeric options fall back to defaults. viewportWidth / viewportHeight / htmlFontSize must be positive finite numbers (otherwise they fall back to 375 / 667 / 37.5). unitPrecision must be a non-negative finite integer (otherwise 5) and is clamped to a maximum of 20 to avoid floating-point overflow. ignoreThreshold must be a non-negative finite number (otherwise 1).
• Excluded selectors skip nested CSS too. When excludeSelectors matches a rule, declarations in its nested rule / at-rule subtree are left unchanged as well. For example, with excludeSelectors: ['.skip'], .skip { .child { width: 10px } } is not converted.
• Unsupported targetUnit. Only 'vw', 'vh', 'rem', and 'vw&rem' are supported. Any other value (including a wrong case like 'VW') emits a single PostCSS warning and performs no conversion.
• The vw&rem fallback combo only applies to vw/rem. The 'vh' mode emits a single vh declaration with no rem fallback.

targetUnit: 'vh' mode

Use the 'vh' mode when a value should scale against the viewport height.

/* Input */
.test {
  height: 66.7px;
}

/* Output */
.test {
  height: 10vh;
}

targetUnit: 'vw&rem' mode

If you want to use vw units but are concerned about browser compatibility, you can use the 'vw&rem' mode. For example:

/* Input */
.test {
  border: 3.75px solid #fff;
}

/* Output */
.test {
  border: 0.1rem solid #fff;
  border: 1vw solid #fff;
}

For browsers that don't support vw, it will automatically use rem for layout.

Note: If you need to limit max/min width of the layout, this mode is not suitable for you

PX case sensitivity

The conversion process is case sensitive. You can use PX to avoid conversion in special cases.

/* Input */
.test {
  padding: 3.75px 3.75PX;
}

/* Output */
.test {
  padding: 1vw 3.75PX;
}

Performance Optimizations

Compared to the original version, this project includes the following optimizations:

• More efficient CSS parsing and processing logic
• Reduction of unnecessary calculations and conversion operations
• Optimized file processing workflow, improving processing speed for large projects

License

This project is licensed under the MIT License - see the LICENSE file for details