postcss-js-styled-core

🔀 Fork from 43081j/postcss-js-core

This project is forked from the original postcss-js-core by James Garbutt.

English | 中文

English

postcss-js-styled-core provides common functionality needed by various css-in-js custom PostCSS syntaxes.

Many css-in-js syntaxes do much of the same work, with slight variations on what they support and how they work. This module aims to provide the basic building blocks for those situations.

Installation

npm install postcss-js-styled-core

Usage

Let's say your syntax makes use of tagged template literals named css.

You can create your PostCSS syntax like so:

import {
  createParser,
  createStringifier
} from 'postcss-js-styled-core';

const options = {
  id: 'my-syntax',
  tagNames: ['css']
};

export = {
  parse: createParser(opts),
  stringify: createStringifier(opts)
};

If you then use this as a PostCSS/stylelint custom syntax, it will parse the following code:

const foo = css`
  div { color: blue; }
`;

Options

When creating a parser/stringifier, you can specify some options. These are as follows:

{
  // Required - an identifier for your syntax
  id: 'my-syntax',

  // Tagged templates to look for
  tagNames: ['css'],

  // Custom sub-parser
  parser: lessSyntax.parse,

  // Custom sub-stringifier _class_
  stringifier: require('postcss-less/lib/LessStringifier.js')

  // Custom babel options for when parsing source JS
  babelOptions: { ... },

  // Custom function for generating placeholders for expressions
  placeholder: customPlaceholderFn
}

Tag names

We currently only support CSS in tagged template literals. The tags we consider as stylesheets are specified by tagNames in the options object.

Any tagged templates using these names will have their contents treated as CSS and extracted into PostCSS.

Two forms are supported:

• Exact tag names (e.g. ['css'])
• Tag name prefixes (e.g. ['css.*'] would match css.foo, it is not a RegExp)

Sub-syntax

You may want to support a "syntax within a syntax". For example, LESS sources inside your JavaScript files.

In order to do this, you must pass the syntax's parser and stringifier class in your options.

For example:

createParser({
  // ...
  parser: require('postcss-less').parse,
  stringifer: require('postcss-less/lib/LessStringifier.js')
});

Importantly, you must pass the class of the stringifier rather than the stringify function. This is so we can correctly extend it.

Two common ones are (at time of writing this) located at:

• SCSS - postcss-scss/lib/scss-stringifier.js
• LESS - postcss-less/lib/LessStringifier.js

中文

postcss-js-styled-core 为各种 css-in-js 自定义 PostCSS 语法提供通用功能。

许多 css-in-js 语法做着大致相同的工作，只是在支持的内容和工作方式上有细微差异。本模块旨在为这些场景提供基础构建模块。

安装

npm install postcss-js-styled-core

使用方法

假设你的语法使用名为 css 的标签模板字面量。

你可以像这样创建你的 PostCSS 语法：

import {
  createParser,
  createStringifier
} from 'postcss-js-styled-core';

const options = {
  id: 'my-syntax',
  tagNames: ['css']
};

export = {
  parse: createParser(opts),
  stringify: createStringifier(opts)
};

然后将其作为 PostCSS/stylelint 自定义语法使用时，它将解析以下代码：

const foo = css`
  div { color: blue; }
`;

配置选项

创建 parser/stringifier 时，可以指定一些选项，如下所示：

{
  // 必需 - 语法的标识符
  id: 'my-syntax',

  // 要查找的标签模板
  tagNames: ['css'],

  // 自定义子解析器
  parser: lessSyntax.parse,

  // 自定义子字符串化器 _类_
  stringifier: require('postcss-less/lib/LessStringifier.js')

  // 解析源 JS 时的自定义 babel 选项
  babelOptions: { ... },

  // 用于生成表达式占位符的自定义函数
  placeholder: customPlaceholderFn
}

标签名称

目前我们仅支持标签模板字面量中的 CSS。我们视为样式表的标签由选项对象中的 tagNames 指定。

使用这些名称的任何标签模板都将其内容视为 CSS 并提取到 PostCSS 中。

支持两种形式：

• 精确标签名（例如 ['css']）
• 标签名前缀（例如 ['css.*'] 将匹配 css.foo，这 不是 正则表达式）

子语法

你可能需要支持"语法中的语法"。例如，JavaScript 文件中的 LESS 源代码。

为此，你必须在选项中传递语法的 parser 和 stringifier 类。

例如：

createParser({
  // ...
  parser: require('postcss-less').parse,
  stringifer: require('postcss-less/lib/LessStringifier.js')
});

重要的是，你必须传递 stringifier 的 类 而不是 stringify 函数。 这样我们才能正确地扩展它。

两个常用的（在撰写本文时）位于：

• SCSS - postcss-scss/lib/scss-stringifier.js
• LESS - postcss-less/lib/LessStringifier.js

License

MIT © James Garbutt