postcss-map

PostCSS plugin enabling configuration maps.

Installation

npm install postcss-map --save-dev

or

yarn add postcss-map --save-dev

Usage

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-map');

let input = fs.readFileSync('input.css', 'utf8');

let opts = {
  basePath: 'css',
  maps: ['example.yml', 'breakpoints.yml', 'fonts.yml'],
};

postcss()
  .use(map(opts))
  .process(input)
  .then(result => {
    fs.writeFileSync('output.css', result.css);
  });

Example usage from declaration values

map:

# example.yml
foo:
  bar:
    baz: 'yeah!'

input:

.baz {
  content: map(example, foo, bar, baz);
}

output:

.baz {
  content: 'yeah!';
}

Example usage from at-rules parameters

map:

# breakpoints.yml
small: 320px
medium: 321px
large: 800px

input:

@media (min-width: map(breakpoints, medium)) {
  .test {
    width: 100%;
  }
}

output:

@media (min-width: 321px) {
  .test {
    width: 100%;
  }
}

Example from declaration blocks

map:

# fonts.yml
regular:
  font-family: "'Spinnaker Regular', sans-serif"
  font-weight: 'normal'
  font-feature-settings: "'onum', 'kern', 'liga', 'dlig', 'clig'"
  font-kerning: 'normal'
bold:
  font-family: "'Spinnaker Bold', sans-serif"
  font-weight: 'normal'
  font-feature-settings: "'onum', 'kern', 'liga', 'dlig', 'clig'"
  font-kerning: 'normal'

input:

.whatever {
  @map fonts regular;
}

output:

.whatever {
  font-family: 'Spinnaker Regular', sans-serif;
  font-weight: normal;
  font-feature-settings: 'onum', 'kern', 'liga', 'dlig', 'clig';
  font-kerning: normal;
}

Example usage with literal objects

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-map');

let input = fs.readFileSync('input.css', 'utf8');

let opts = {
  basePath: 'css',
  maps: [
    {
      dummy: {
        one: 1,
        two: 2,
      },
    },
    'example.yml',
    'breakpoints.yml',
    'fonts.yml'
  }]
};

postcss()
  .use(map(opts))
  .process(input)
  .then(result => {
    fs.writeFileSync('output.css', result.css);
  });

input:

.whatever {
  content: map(dummy, one);
}

.baz {
  content: map(example, foo, bar, baz);
}

output:

.whatever {
  content: 1;
}

.baz {
  content: 'yeah!';
}

Example usage with literal objects and short syntax

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-map');

let input = fs.readFileSync('input.css', 'utf8');

let opts = {
  maps: [
    {
      one: 1,
      two: 2,
    },
  ],
};

postcss()
  .use(map(opts))
  .process(input)
  .then(result => {
    fs.writeFileSync('output.css', result.css);
  });

input:

.whatever {
  content: map(one);
}

output:

.whatever {
  content: 1;
}

Options

basePath

type: String
default: process.cwd
Base path to retrieve maps from.

maps

type: Array
default: []
An array representing maps files to load and parse. Map files can either be in YAML or JSON format.
You can also pass literal objects directly into the Array.

defaultMap (short syntax)

type: string
default: config

A shorter syntax is also available, so you don't have to type the map name on each call. To enable it you need to either have a map called config or only one map in your settings.

let opts = {
  basePath: 'css',
  maps: ['foo.yml']
  // OR
  maps: ['config.yml', 'breakpoints.yml']
};

map:

# config.yml
foo: 'foo value'

input:

.short {
  content: map(foo);
}

output:

.short {
  content: 'foo value';
}

Context

Used in conjunction with postcss-plugin-context you can benefit from contextualized maps and leverage the short syntax.

@context brandColors {
  h1 {
    color: map(primary);
  }
}

Credits

• Pascal Duez
• Bogdan Chadkin

Licence

postcss-map is unlicensed.