postcss-custom-property-maps

Interlope external value maps with css as custom properties. Supports Javascript module, YAML file, or JSON file. Use before [postcss-custom-properties] to insert the map values directly into the css.

Installation

npm install postcss-custom-property-maps --save-dev

or

yarn add postcss-custom-property-maps --save-dev

Usage

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-custom-property-maps');
 
let input = fs.readFileSync('input.css', 'utf8');
 
let opts = {
  basePath: 'css',
  maps: ['example.js', 'breakpoints.yml', 'fonts.json'],
};
 
postcss()
  .use(map(opts))
  .process(input)
  .then(result =>
    fs.writeFileSync('output.css', result.css);
  );

Options

basePath

type: String
default: process.cwd
Directory to resolve map paths against.

includeUnused

type: boolean
default: false
If true generate custom properties for all map variables. Otherwise only generate custom properties for used variables.

maps

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

defaultMap (short syntax)

type: string
default: config

A map to resolve values against if another map is not found. This allows a shorter syntax where you can leave off the map name.

For Example

let opts = {
  defaultMap: 'values'
  maps: ['colors.yml', 'values.yml']
};

maps:

# colors.yml 
main: 'red'

# values.yml 
foo: 'foo value'

input:

.short {
  content: map(foo); /* Resolves against 'values.yml' */
  color: map(colors, main); /* Resolves against 'colors.yml' */
}

output:

:root {
  --values-foo: 'foo value';
  --colors-main: 'red';
}
 
.short {
  content: var(--values-foo);
  color: var(--colors-main);
}

If you only have a single map all values will automatically resolve against it.

Example usage

declaration values

maps:

# colors.yml 
red: '#FF0000'

# example.yml 
foo:
  bar:
    baz: 'yeah!'
 
main-color: map(colors, red)

input:

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

output:

:root {
  --colors-red: #ff0000;
  --example-main-color: var(--colors-red);
  --example-foo-bar-baz: yeah!;
}
 
.baz {
  content: var(--example-foo-bar-baz);
  color: var(--example-main-color);
}

With postcss-custom-properties

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-custom-property-maps');
const customProperties = require('postcss-custom-properties');
 
let input = fs.readFileSync('input.css', 'utf8');
 
postcss()
  .use(
    map({
      maps: ['example.yml'],
    })
  )
  .use(customProperties())
  .process(input)
  .then(result =>
    fs.writeFileSync('output.css', result.css);
  );

maps:

# example.yml 
foo: yeah!

input:

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

output:

.baz {
  content: yeah!;
}

Javascript module

maps:

// example.js
module.exports = {
  foo: 'yeah!',
};

input:

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

output:

:root {
  --example-foo: yeah!;
}
 
.baz {
  content: var(--example-foo);
}

At-rule parameters

map:

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

input:

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

output:

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

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:

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

Literal objects

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-custom-property-maps');
 
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:

:root {
  --dummy-one: 1;
  --example-foo-bar-baz: yeah!;
}
 
.whatever {
  content: var(--dummy-one);
}
 
.baz {
  content: var(--example-foo-bar-baz);
}

Literal objects and short syntax

const fs = require('fs');
const postcss = require('postcss');
const map = require('postcss-custom-property-maps');
 
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:

:root {
  --one: 1;
}
 
.whatever {
  content: var(--one);
}

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

Thanks to Pascal Duez and Bogdan Chadkin for the inital project postcss-map.