Postcss-px-to-viewport: a tool for creating scalable interfaces on any display

Most mobile and cross-platform web developers have encountered the problem at some point: you need your web app to scale neatly to the device screen size, regardless of which of the many thousands of devices there are out there, but your units only have one design layout width, mainly mobile. Or perhaps you need to create a per-device stylesheet for a truly scalable cross-platform UI, and want to use a scaled version of an original to base it upon. In either case, converting everything by hand is laborious and inconvenient.

Grappling with this problem in one of our projects, the Med.me app, our leading frontend developer Dmitriy Karpunin came up with the idea of using a post-processor to convert CSS values from one set of units to another, and that’s how postcss-px-to-viewport, a plug-in for PostCSS that converts px values to viewport units (vw, vh, etc.), was born.

For example, if you specify a notional horizontal resolution of 640 pixels and you specify a horizontal distance of 32px, the plug-in will convert that to 5vw in the output, because 32 pixels is 5% of the 640 pixel viewport width.

The plug-in also has plenty of options for customisation, to control exactly which values to convert, and where, and based upon which notional resolution.

Installation

Installation is straightforward with npm:

$ npm install postcss-px-to-viewport --save-dev

or with yarn, if you prefer:

$ yarn add -D postcss-px-to-viewport

Configuration

To configure the plug-in, add a 'postcss-px-to-viewport' object to your postcss.config.js as shown below:

module.exports = {
  plugins: {
    ...
    'postcss-px-to-viewport': {
       unitToConvert: 'px',
       viewportWidth: 320,
       unitPrecision: 5,
       propList: ['*'],
       viewportUnit: 'vw',
       fontViewportUnit: 'vw',
       selectorBlackList: [],
       minPixelValue: 1,
       mediaQuery: false,
       replace: true,
       exclude: [],
       landscape: false,
       landscapeUnit: 'vw',
       landscapeWidth: 568
 
    }
  }
}

The options listed above are shown with their default values, and any that you don't wish to override can be omitted.

To use postcss-px-to-viewport with gulp-postcss, add a task to your gulpfile.js along the lines of the below:

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var pxtoviewport = require('postcss-px-to-viewport');
 
gulp.task('css', function () {
 
    var processors = [
        pxtoviewport({
            viewportWidth: 320,
            viewportUnit: 'vmin'
        })
    ];
 
    return gulp.src(['build/css/**/*.css'])
        .pipe(postcss(processors))
        .pipe(gulp.dest('build/css'));
});

Widely used across Asia

One day in Summer 2018, we discovered an active community had sprung up around the plug-in in China — suddenly, the issues, pull requests, and forks came flooding in.

Much of Asia, but China, in particular, suffers from an active proliferation of devices that developers are tasked with supporting, and postcss-px-to-viewport quickly became invaluable to many!

We quickly realised that it would be helpful if the plug-in came with instructions in Chinese, not just English, and we were thrilled when a community volunteer answered our call and contributed a Chinese-language Readme for the project.

postcss-px-to-viewport is an excellent example of a utility that does one thing and does it well, and we encourage others to open similar tools they may have written. And, if you encounter any problem in the development of your project and cannot find a ready-made solution, we are here to help you develop a plugin or even a software that will solve your problem and possibly help thousands of other developers.