css-codemod - npm Package Compare versions

Comparing version 0.0.0-pr.7.1.f4c705a to 0.0.0-pr.7.2.ae01410

package.json

 {
-  "version": "0.0.0-pr.7.1.f4c705a",
+  "version": "0.0.0-pr.7.2.ae01410",
   "license": "MIT",
@@ -4,0 +4,0 @@ "name": "css-codemod",

README.md

 # :snake: css-codemod
 
-css-codemod is a toolkit for running codemods (a.k.a. transforms) over many CSS files.
+css-codemod is a toolkit for running codemods over many CSS files to transform code.
 
-Powered by [PostCSS](https://postcss.org) so the existing tooling and community can be leveraged.
+Powered by [PostCSS](https://postcss.org):
 
-- Any [PostCSS syntax parser and stringifier](https://github.com/postcss/postcss/blob/main/docs/syntax.md) can be added.
-- Any [PostCSS plugin](https://github.com/postcss/postcss/blob/main/docs/plugins.md) can be added,
+- Any [PostCSS syntax parser and stringifier](https://github.com/postcss/postcss/blob/main/docs/syntax.md) can be added. This extends support for additional syntaxes like SASS and LESS.
+- Any [PostCSS plugin](https://github.com/postcss/postcss/blob/main/docs/plugins.md) can be added. This allows running any plugin as a one-off transform. This can be useful if you want to run a plugin once and remove it from a build tool.
+- Any [PostCSS helpers](https://postcss.org/api/) for working with nodes and the abstract syntax tree can be used to transform CSS.
 
@@ -14,3 +15,3 @@ ## Install
 
-First, using [npx](https://www.npmjs.com/package/npx) to execute the transform without need to explicitly install `css-codemod`.
+First, using [npx](https://www.npmjs.com/package/npx):
 
@@ -21,3 +22,3 @@ ```bash
 
-Second, install `css-codemod` as a dependency and execute with your package manager of choice.
+Second, install and execute `css-codemod` with a package manager:
 
@@ -29,3 +30,3 @@ ```bash
 
-Third, install `css-codemod` globally.
+Third, globally install `css-codemod`:
 
@@ -80,9 +81,10 @@ ```
 export const transform: Transform = (fileInfo, api) => {
-  // Implement the transform.
-  // See below for more details on the API.
+  // Implement the transform. See below for more details on the API.
 };
 
-// Optionally defined a named `parser` export to configure the PostCSS parser.
-//   Docs: https://postcss.org/api/#parser
+// Optionally define a named `parser` export to configure the PostCSS parser.
 // export const parser = ...;
+
+// Optionally define a named `plugins` export to configure PostCSS plugins.
+// export const plugins = [...];
 ```
@@ -117,2 +119,16 @@
 
+### `parser`
+
+Define the [PostCSS parser](https://postcss.org/api/#parser) to use when parsing the CSS files. This is useful for adding support for additional syntaxes.
+
+To configure, export `parser` with a PostCSS parser from the transform file.
+
+Note: if you define a `parser` than you almost always want to pass the `stringifier` from the same package to `root.toString(stringifier)`. This will guarantee the output is properly formatted using the same syntax.
+
+### `plugins`
+
+Define [PostCSS plugins]() to use when parsing the CSS files. This is useful for running plugins one-off, for example to upgrade syntax or perform other transformations already provided as plugins. Creating a custom plugin is one way that transform logic can be shared with other PostCSS tools and `css-codemod`. If you only want to share the codemod, then creating a transform file and sharing it is another option that requires less setup from others.
+
+To configure, export `plugins` with an array of PostCSS plugins from the transform file.
+
 ### Example
@@ -124,3 +140,6 @@
 import { Transform } from 'css-codemod';
+// Example PostCSS syntax extension. This isn't required.
 import { parse, stringify } from 'postcss-scss';
+// Example PostCSS plugin. This isn't required.
+import calc from 'postcss-calc';
 
@@ -148,2 +167,3 @@ export const transform: Transform = (fileInfo, api) => {
   // Since a string is returned this will be written back to the file.
+  //
   // Note: in this example the `postcss-scss` package is used to add
@@ -157,4 +177,12 @@ // SCSS syntax support. The stringifier is passed when we call `toString` to
 // This configures PostCSS to correctly parse SCSS syntax.
-//   Docs: https://postcss.org/api/#parser
+//   API docs: https://postcss.org/api/#parser
+//   Syntax docs: https://github.com/postcss/postcss/blob/main/docs/syntax.md
 export const parser = parse;
+
+// Note: in this example the `postcss-calc` package is used to compute `calc` expressions.
+// This is used only as an example. Say you wanted to simplify all the complex `calc`
+// expressions? Or, maybe you want to remove a plugin from the build pipeline and run it once?
+//   API docs: https://postcss.org/api/#acceptedplugin
+//   Plugin docs: https://github.com/postcss/postcss/blob/main/docs/plugins.md
+export const plugins = [calc({})];
 ```
@@ -172,4 +200,4 @@
 
-**css-codemod** is inspired by tools like [`jscodeshift`](https://github.com/facebook/jscodeshift) to streamline CSS transformations whether it be an evolving codebase, or adopting newer syntax.
+css-codemod is inspired by tools like [`jscodeshift`](https://github.com/facebook/jscodeshift) to streamline CSS transformations whether it be an evolving codebase, or adopting newer syntax.
 
-Read [CSS codemods with PostCSS](https://www.skovy.dev/blog/css-codemods-with-postcss) for a conceptual overview of how this toolkit works.
+Read [CSS codemods with PostCSS](https://www.skovy.dev/blog/css-codemods-with-postcss) for a conceptual overview of how this toolkit works and the initial motivation.

No alert changes

Improved metrics

Total package byte prevSize

23765

increased by8.96%

Number of lines in readme file

195

increased by16.77%

No dependency changes