parse/stringify/write css in js

html docs

  npm install --save-exact @magic/css

@magic/css includes a cli script that can handle most usecases the internal javascript api allows.

to use this cli from any directory, npm install -g @magic.css is a useful shortcut. after the global install, you can just call mcss from anywhere in your terminal.

after installation, add: "mcss": "mcss" to your package.json "scripts" section and then npm run mcss to see the help output below.

@magic/css
commands:
stringify - convert css in js to css
parse     - convert css in js to an array of key value pairs
full      - get a full result object.

flags:
--minified - output minified css - alias: ["--m", "-m"]
--help     - alias: ["-h"]
--out      - directory to write output files to. omit to print to stdout - alias: ["--o", "-o"]
--in       - directory with source files, needs index.js to exist - alias: ["--i", "-i"]

examples:
mcss parse --in ./styles --out ./css
mcss stringify --in ./styles --out ./css
mcss full --in ./styles --out ./css

import css from '@magic/css'

import css from '@magic/css'

const style = {
  body: {
    color: 'green',
  },
  '.class': {
    color: 'orange',
  },
  '#id': {
    color: 'purple',
  },
}

css(style)

// returns
Object {
  // nicely formatted css string
  css: 'body {\n  color: green;\n}\n.class {\n  color: orange;\n}\n#id{\n  color: purple;\n}\n',
  // minimal whitespace
  minified: 'body{color:green}.class{color:orange}#id{color:purple}',
  // array of used classes if any
  classes: ['.class'],
  // array of used ids if any
  ids: ['#id'],
  // array of used selectors
  selectors: ['body', '.class', '.id'],
  // ast of this css object
  parsed: [
    ['body', { color: 'green' }],
    ['.class': { color: 'orange' }],
    ['#id': { color: 'purple' }],
  ],
}

const style = {
  '.className': {
    color: 'green',
  },
}
await css.stringify(style)

// .className { color:green; }

const style = {
  div: {
    color: 'red',
    '&:hover': {
      color: 'green',
    },
  },
}

await css.stringify(style)

// div { color: red; }
// div:hover { color: green; }

to suffix some of the selectors, add a & to any of them except the first one

const style = {
  div: {
    '.class1, &.class2': {
      color: 'red',
    },
  },
}

await css.stringify(style)

// div .class1, div.class2 { color: red; }

if you add the & at the start of the string, all of the selectors will have it applied

const style = {
  div: {
    '&.class1, .class2': {
      color: 'orange',
    },
  },
}

await css.stringify(style)

// div.class1, div.class2 { color: orange; }

to prefix the parent of the selector using the child selectors, add a & at the end of any selectors but the last one.

const style = {
  '.class': {
    'p&, :hover': {
      color: 'orange',
    },
  },
}

await css.stringify(style)

// p.class, .class:hover { color: orange; }

if the & is at the end of a selector, the & will be applied to each of them.

const style = {
  '.class': {
    'div, p&': {
      color: 'orange';
    },
  },
}

await css.stringify(style)

// div.class, p.class { color: orange; }

to prefix the parent with a space, use a double && instead of a single &

const style = {
  '#id': {
    '.class2&&, .class3': {
      color: 'orange';
    },
  },
}

await css.stringify(style)

// .class2 #id, #id.class3 { color: orange; }

if the && is at the end of a selector, the && will be applied to each of them.

const style = {
  '.class': {
    'div, p&&': {
      color: 'orange';
    },
  },
}

await css.stringify(style)

// div .class, p .class { color: orange; }

const style = {
  '.className': {
    '#id': {
      color: 'orange',
    },
  },
}

css.parse(style)

// ast

const style = {
  '.className': {
    '#id': {
      color: 'white',
    },
  },
}

await css.stringify(
  style,
) // minified string
`.className #id{color:white;}`

const style = {
  '.className': {
    '#id': {
      color: opts.textColor,
    },
  },
}

// writes styles to ./out.css
await css.write(style)

// writes styles to ./outfile.css
await css.write(style, { OUTFILE: './outfile.css' })

Mediaqueries can use the vars.widths object to determine appropriate breakpoint sizes.

Default widths:

opts.widths = {
  tablet: '500px',
  laptop: '900px',
  desktop: '1200px',
  agency: '1600px',
}

const style = {
  [`@media screen and (min-width: ${vars.widths?.tablet || '500px'})`]: {
    '#id': {
      color: opts.textColor,
    },
  },
}

await css.stringify(
  style,
) // css string
`
@media screen and (min-width: 500px) {
  #id {
    color: green;
  }
}
`

const style = {
  '@font-face': {
    family: 'font-name',
    url: '/fonts/',
    styles: ['normal', 'italic'],
    weights: [400, 600],
  },
}

await css.stringify(
  style,
) // css string
`
@font-face {
  font-family: "font-name";
  font-style: normal;
  font-weight: normal;
  src: url('/fonts/font-name-400-normal.eot\');
  src: url('/fonts/font-name-400-normal.eot#iefix') format('embedded-opentype'),',
  url('/fonts/font-name-400-normal.ttf') format('truetype'),',
  url('/fonts/font-name-400-normal.woff') format('woff'),',
  url('/fonts/font-name-400-normal.woff2') format('woff2'),',
  url('/fonts/font-name-400-normal.svg#font-name') format('svg');',
}
`
// ... repeated for all styles and weights that were defined

return classes and ids as well

Added media queries

• returns a promise! no longer sync.
• autoprefixer and postcss added

supports @font-face declarations

added fontDir option to font-face declarations

update deps to fix security issues

added @keyframes for animations

css.parse now converts deep arrays into one object before parsing

• css.stringify now makes a bit nicer mediaquery and keyframe lines.
• css.parse should now order media queries to the end of the css

css.parse does a better job of keeping order of incoming objects intact

• FIX: multiple parent selectors 'h1,h2,h3' that should get appended with a &:hover etc now correctly append the suffix to every parent
• FEATURE: & can be at the end of a selector, in which case the selector gets prepended to it's parent.

FIX: css gets returned in almost the same order it got passed in. turns out that javascript objects do not make this as easy as hoped.

use esmodules

update @magic/types to not break if es modules get passed into the styles

• update @magic/deep to use ecmascript module version
• update postcss, autoprefixer

update dependencies

update dependencies

add @magic/log to dependencies

update autoprefixer

update postcss

update postcss

update @magic/deep

require node >= 13.5.0

update postcss

update autoprefixer

update postcss

• bump required node version to 14.2.0
• write is async now

• update autoprefixer, dependencies

• update dependencies

update autoprefixer

update autoprefixer

• move no-spy to devdeps
• update dependencies

update autoprefixer

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies simplify font-face handling

• bump required node version to 14.15.4
• update dependencies

• font-face handles non-array weights, types and styles
• font-face uses woff and woff2 as default font types
• font-face uses weight 400 and styles 'normal' as defaults

update dependencies

update dependencies (@magic/fs)

• update dependencies
• css.selectors returns arrays instead of strings

update dependencies

update dependency autoprefixer

update dependency @magic/fs

remove local implementation of camel2kebab, use @magic/cases instead

update dependencies

FIX: update @magic/cases, which fixes overflow-x and other css props that end with an uppercase character overflowX is output as overflowx in earlier versions, the regex expected lowercase characters after the uppercase char

update dependencies

update dependencies

update dependencies

update dependencies

• update dependencies
• added font v2 to allow handling of local() fonts (see https://magic.github.io/css/#styles-webfonts)
• woff2 files are placed before woff files
• use single quotes in output css
• add cli

• css props can be arrays to provide css overloads { color: ['green', 'red'] } turns into color: green; color: red;
• update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

• update dependencies
• update docs to reflect usage of vars.widths.{tablet|laptop|desktop}
• add defaults for opts.widths, to make sure we can use media queries at all times.

opts.widths = {
  tablet: '500px',
  laptop: '900px',
  desktop: '1200px',
  agency: '1600px',
}

update dependencies

update dependencies

update dependencies

update dependencies

update dependencies

• update dependencies

• update dependencies

• update dependencies

...