Migration Guide

Move legacy packages to postcss-rule-unit-converter without changing behavior.

• Overview: README.md
• API: API.md
• Recipes: COOKBOOK.md
• Preset authoring: PRESET_AUTHORING.md

When To Migrate

Prefer postcss-rule-unit-converter when you need:

• one plugin that handles multiple unit systems
• custom preset authoring
• ordered rule composition
• one shared API instead of several package-specific APIs

Keep the legacy packages when you need strict backward compatibility for existing config or public package names.

postcss-rem-to-viewport

Legacy:

import remToViewport from 'postcss-rem-to-viewport'

remToViewport({
  rootValue: 375,
  transformUnit: 'vw',
  propList: ['font', 'font-size', 'line-height', 'letter-spacing'],
  unitPrecision: 16,
})

Unified:

import unitConverter, { presets } from 'postcss-rule-unit-converter'

unitConverter({
  propList: ['font', 'font-size', 'line-height', 'letter-spacing'],
  unitPrecision: 16,
  rules: [
    presets.remToViewport({
      rootValue: 16,
      viewportWidth: 375,
      to: 'vw',
    }),
  ],
})

Option mapping:

• rootValue -> viewportWidth
• transformUnit -> to
• minRemValue -> minValue
• propList, selectorBlackList, replace, mediaQuery, exclude, disabled -> same option names

postcss-rem-to-responsive-pixel

Legacy:

import remToResponsivePixel from 'postcss-rem-to-responsive-pixel'

remToResponsivePixel({
  rootValue: 16,
  transformUnit: 'rpx',
  propList: ['*'],
})

Unified:

import unitConverter, { presets } from 'postcss-rule-unit-converter'

unitConverter({
  propList: ['*'],
  rules: [
    presets.remToRpx({
      rootValue: 16,
    }),
  ],
})

For transformUnit: 'px', use presets.remToPx({ rootValue }).

Option mapping:

• rootValue -> rootValue
• transformUnit: 'px' -> presets.remToPx(...)
• transformUnit: 'rpx' -> presets.remToRpx(...)
• minRemValue -> minValue
• processorStage -> not needed; postcss-rule-unit-converter runs in Once
• propList, selectorBlackList, replace, mediaQuery, exclude, disabled -> same option names

postcss-units-to-px

Legacy:

import unitsToPx from 'postcss-units-to-px'

unitsToPx({
  unitMap: {
    rem: 16,
    vw: 3.75,
    rpx: 0.5,
  },
})

Unified:

import unitConverter, { presets } from 'postcss-rule-unit-converter'

unitConverter({
  rules: presets.unitsToPx({
    unitMap: {
      rem: 16,
      vw: 3.75,
      rpx: 0.5,
    },
  }),
})

Fallback transform example:

unitConverter({
  rules: presets.unitsToPx({
    unitMap: [
      [/^q$/, null],
      ['vw', false],
    ],
    transform(value, unit, context) {
      return unit === 'q' && context.prop === 'margin' ? value * 4 : undefined
    },
  }),
})

Migration notes:

• presets.unitsToPx() covers the default rem/em/vw/vh/vmin/vmax/rpx -> px set.
• Object unitMap values merge over the defaults, matching postcss-units-to-px.
• Map and array unitMap values preserve user order and do not merge defaults.
• A unit rule of false skips that unit.
• A unit rule of null or runtime undefined falls back to transform(value, unit, context).

postcss-pxtrans

postcss-pxtrans has platform presets plus directive comment handling. Keep it if you rely on:

• createDirectivePlugin()
• platform-driven config
• Harmony PX/Px/pX -> ch behavior as a dedicated package API

If you only need the size conversion logic, the equivalent rule shape is:

import unitConverter from 'postcss-rule-unit-converter'

unitConverter({
  rules: [
    {
      from: unit => unit === 'px' || unit === 'rpx',
      to: 'rem',
      transform(value, context) {
        return value / 34.18803418803419
      },
    },
  ],
})

For exact pxtrans parity, you usually still want postcss-pxtrans, because it packages platform defaults, directive handling, and edge-case compatibility in one API.

Custom Preset Strategy

If your app currently switches between multiple legacy plugins, prefer writing one local preset group:

import { definePresetGroup } from 'postcss-rule-unit-converter'

export const appPresetGroup = definePresetGroup((options = {}) => {
  return [
    // rem -> rpx
    // px -> rpx
    // vw -> px
  ]
})

This keeps app-specific logic in one place instead of distributing it across multiple plugin packages.