Migration guide

English · 简体中文

Migrating from any "convert px to viewport units" setup follows the same steps: get the output to line up first, then enable the new capabilities one at a time. Map concepts rather than hunting for an identically named option.

Step one: swap in the equivalent only

Introduce no new features yet; get the new output as close to the old as possible:

adaptiveMatrix({
  profiles: {
    app: {
      designWidth: 375,     // your old viewport base width
      query: false,         // do not generate a media query wrapper
    },
  },
  precision: 5,             // your old decimal places
  strategy: 'viewport',     // plain vw, the same shape as before
  libraries: false,         // component-library adaptation off for now too
})

strategy: 'viewport' emits unbounded vw; fluid bounds are unnecessary in this mode. A sole profile becomes the default automatically. This is a starting point, not a byte-for-byte compatibility guarantee: match property filters, ignored values, hairline handling and rounding against your existing output. For example, the default hairline: 1 preserves a 1px border; use hairline: 0 only if your old build intentionally scales it.

Step two: map the concepts

What you used to configure	Where it lives here
Design file width / viewport base width	a profile's designWidth
Decimal places	precision
Output unit	unit, or a profile's unit
Property allow/deny list	propList (supports * and !)
Selector blacklist	selectorExclude
Value blacklist	valueExclude
Minimum pixel value to convert	minPixelValue
File include/exclude	include / exclude, which also accept functions
Keep the original declaration as a fallback	preserveOriginal: true
Root container selector	root.selector
Maximum desktop display width	fluid.maxWidth + rootMaxWidth
Ignore comments	adaptive-ignore / adaptive-ignore-next / adaptive-ignore-rule

Existing /* px-to-viewport-ignore(-next) */ and /* mobile-ignore(-next) */ directives keep working during migration; they remain in the output for the same second-pass guarantee as the native comments. No compatibility option is required. The old postcss-pxtorem uppercase-unit trick (1PX) is intentionally not an ignore signal here because CSS units are case-insensitive — use an explicit comment instead.

Check existing math expressions

Conversion is not byte-compatible with every legacy plugin. In a local comparison with postcss-px-to-viewport@1.1.1, using a 375px canvas and viewport output, min(24px, 50vw) became min(6.4vw, 50vw) there but stayed unchanged here. Adaptive Matrix protects bounding expressions that already contain viewport/container units so precompiled output is not converted again. Audit authored min() / max() / clamp() expressions during migration: write the intended fluid expression explicitly when a pixel term must scale. Uppercase input units are also converted here; do not rely on PX as an ignore marker.

Separate layout decisions

Landscape is not a global switch. Create a landscape profile with an explicit media query, and landscape gets its own design width and scaling range instead of a ratio derived from portrait.

Desktop width is not a design width. If desktop is just the mobile version centred, it has no design file of its own: use the app profile with rootMaxWidth. If desktop has its own design file, give it its own designWidth and put the differences in @adaptive pc. Those two used to be expressed by the same option; here they are two different structures.

Step three: enable the rest

Once the visuals match, turn things on in order:

1. Remove strategy: 'viewport' to restore the default strategy. Add fluid bounds only if the design needs them: { maxWidth: 480 } sets a ceiling, { minWidth: 320 } sets a floor, and both give clamp(). Without bounds, lengths remain unbounded; switching the strategy alone does not invent a range. Text also regains the default rem/viewport hybrid;
2. Remove query: false, or switch to appPcPreset to bring in a desktop profile;
3. Drop libraries: false, so component libraries adapt on their own canvases (see Component libraries). This step usually lets you delete the entire ignore list your old setup needed for them;
4. Configure root when you want a centred column, and fixedContainingBlock handles fixed-position elements along with it.

Acceptance

• Keep the old output as a visual baseline;
• Cover 320, 375, 480, 768, 1024, 1440, 1920;
• Check fixed/sticky elements, modals, third-party components and input methods;
• Run 200% browser zoom and keyboard navigation tests — the text hybrid formula pays off exactly there, and only a real test verifies it.