postcss-wrap-selectors

English

A PostCSS plugin that automatically wraps all CSS selectors with a given parent class (e.g., .l-wrapper). Useful for scoping styles to avoid conflicts with legacy or client CSS. Includes examples for both CLI and Gulp usage.

Features

• Scope all selectors under a wrapper class
• Avoids duplicate wrapping if the wrapper already exists
• Automatically excludes html, body, :root
• Skips @keyframes rules
• Configurable via plugin.config.json or options

Installation

npm i -D postcss postcss-cli postcss-wrap-selectors

Peer dependency:

• postcss (v8)

Usage

With PostCSS CLI

postcss.config.js

import wrap from "postcss-wrap-selectors";
import conf from "./plugin.config.json" assert { type: "json" };

export default {
  plugins: [
    wrap({
      wrapper: conf.wrapper ?? ".l-wrapper",
      exclude: conf.exclude ?? ["html", "body", ":root"],
      skipKeyframes: conf.skipKeyframes ?? true,
    }),
  ],
};

Run:

npx postcss input.css -o output.css

With Gulp

gulpfile.js

import gulp from "gulp";
import sass from "gulp-dart-sass";
import postcss from "gulp-postcss";
import wrap from "postcss-wrap-selectors";
import conf from "./plugin.config.json" assert { type: "json" };

export const css = () =>
  gulp
    .src("src/style.scss")
    .pipe(sass({ outputStyle: "expanded" }))
    .pipe(postcss([wrap(conf)]))
    .pipe(gulp.dest("dist"));

export default css;

Example

Input:

.button {
  &--primary {
    color: red;
  }
}

Output:

.l-wrapper .button--primary {
  color: red;
}

Options

| Option | Type | Default | Description | | --------------- | ---------- | --------------------------- | -------------------------------------------- | | wrapper | string | .l-wrapper | Class name to wrap selectors with | | exclude | string[] | ["html", "body", ":root"] | Selectors that should not be wrapped | | skipKeyframes | boolean | true | Whether to skip wrapping inside @keyframes |

Development

Build:

npm run build

Run examples:

cd examples/gulp
npm i
npm run build

cd ../cli
npm i
npm run build

License

MIT

日本語

特定のクラスで全てのセレクタを自動的にラップする PostCSS プラグインです。 クライアント側の既存 CSS がこちらのスタイルを上書きしてしまうケースなどで、 全体を親クラス配下にスコープさせたいときに便利です。 CLI と Gulp の両方の使用例を含んでいます。

特長

• 指定したラップ用クラスで全セレクタをスコープ化
• 既にラップクラスを含むセレクタは重複して付与しない
• html, body, :root などは自動的に除外
• @keyframes 内は自動的にスキップ
• 設定ファイル（plugin.config.json）またはオプションで柔軟に制御可能

インストール

npm i -D postcss postcss-cli postcss-wrap-selectors

ピア依存関係:

• postcss (v8)

使い方

PostCSS CLI の場合

postcss.config.js

import wrap from "postcss-wrap-selectors";
import conf from "./plugin.config.json" assert { type: "json" };

export default {
  plugins: [
    wrap({
      wrapper: conf.wrapper ?? ".l-wrapper",
      exclude: conf.exclude ?? ["html", "body", ":root"],
      skipKeyframes: conf.skipKeyframes ?? true,
    }),
  ],
};

実行:

npx postcss input.css -o output.css

Gulp の場合

gulpfile.js

import gulp from "gulp";
import sass from "gulp-dart-sass";
import postcss from "gulp-postcss";
import wrap from "postcss-wrap-selectors";
import conf from "./plugin.config.json" assert { type: "json" };

export const css = () =>
  gulp
    .src("src/style.scss")
    .pipe(sass({ outputStyle: "expanded" }))
    .pipe(postcss([wrap(conf)]))
    .pipe(gulp.dest("dist"));

export default css;

実行例

入力:

.button {
  &--primary {
    color: red;
  }
}

出力:

.l-wrapper .button--primary {
  color: red;
}

オプション

| オプション | 型 | デフォルト | 説明 | | --------------- | ---------- | --------------------------- | ------------------------- | | wrapper | string | .l-wrapper | ラップに使用するクラス名 | | exclude | string[] | ["html", "body", ":root"] | ラップを除外するセレクタ | | skipKeyframes | boolean | true | @keyframes 内をラップ対象から外すか |

開発方法

ビルド:

npm run build

サンプル実行:

cd examples/gulp
npm i
npm run build

cd ../cli
npm i
npm run build

ライセンス

MIT