css-codemod - npm Package Compare versions

Comparing version 0.0.0-pr.4.4.c5ae6a2 to 0.0.0-pr.4.5.9857f7c

package.json

 {
-  "version": "0.0.0-pr.4.4.c5ae6a2",
+  "version": "0.0.0-pr.4.5.9857f7c",
   "license": "MIT",
@@ -4,0 +4,0 @@ "name": "css-codemod",

README.md

@@ -12,3 +12,3 @@ # :snake: css-codemod
 ```bash
-npx css-codemod ./src/**/*.css -t ./transform.ts
+npx css-codemod "./src/**/*.css" -t ./transform.ts
 ```
@@ -21,7 +21,7 @@
 npm i -D css-codemod
-./node_modules/.bin/css-codemod ./src/**/*.css -t ./transform.ts
+./node_modules/.bin/css-codemod "./src/**/*.css" -t ./transform.ts
 
 # Or, install and execute css-codemod with yarn
 yarn add -D css-codemod
-yarn css-codemod ./src/**/*.css -t ./transform.ts
+yarn css-codemod "./src/**/*.css" -t ./transform.ts
 ```
@@ -31,4 +31,6 @@
 
-The transform file defines the transformations to define. The transform can be written in either JavaScript or TypeScript.
+The transform file defines the transformation to make to each file. The transform can be written in either JavaScript or TypeScript.
 
+It needs to provide a named `transform` export that is a function. This transform function will be invoked for each file that matches the files to process.
+
 ```ts
@@ -41,6 +43,4 @@ // transform.ts
 
-// Define a named `transform` export.
-// Note: it's important the function is named `transform` because that's
-// what the tool expects.
-export const transform: Transform = (file, api) => {
+// Define a named `transform` export function.
+export const transform: Transform = (fileInfo, api) => {
   // Implement the transform.
@@ -78,8 +78,14 @@ };
 
-Define a transform function. This type is provided to explicitly type the exported `transform` function. In general, this should be the only type that needs to be imported. The expected return value is either a CSS string or `null`. When returned a CSS string that will be written back to the original file. When returned `null`, nothing happens and the original file is skipped.
+Define a transform function.
 
+This type is provided to explicitly type the exported `transform` function. In general, this should be the only type that needs to be explicitly imported. The expected return value is either a string or `null`.
+
+- When returned a string it will be written back to the original file. - When returned `null`, nothing happens and the original file is skipped.
+
 ### `TransformFileInfo`
 
-The first argument passed to the `transform` function. It's an object with metadata about the current file being processed by the transform.
+The first argument passed to the `transform` function.
 
+It's an object with metadata about the current file being processed by the transform.
+
 - `path`: the resolved path of the file being transformed.
@@ -90,6 +96,8 @@ - `source`: the file contents source of the file being transformed.
 
-The second argument passed to the `transform` function. It's an object with helpers provided by `css-codemod` to perform transformations.
+The second argument passed to the `transform` function.
 
-- `parse`: parse a raw CSS string into an AST. This returns the root node of the underlying abstract syntax tree to perform mutations. This is performed with [PostCSS](https://postcss.org/) so the returned node is a PostCSS [Root](https://postcss.org/api/#root) node. Refer to the [PostCSS API documentation](https://postcss.org/api/) for documentation and various helpers.
+It's an object with helpers provided by `css-codemod` to perform transformations.
 
+- `parse`: parse a raw CSS string into an AST. This returns the root node of the underlying abstract syntax tree. Transformations can be made by making direct mutations to the underlying node. This is performed with [PostCSS](https://postcss.org/) so the returned node is a PostCSS [Root](https://postcss.org/api/#root) node. Refer to the [PostCSS API documentation](https://postcss.org/api/) for documentation on nodes and various helpers.
+
 ### Example
@@ -131,4 +139,10 @@
 
+### AST Explorer
+
+[AST Explorer](https://astexplorer.net) is recommended when working on transforms. Change the language to "CSS" and the parser to "postcss" to see the underlying abstract syntax tree for a given snippet of CSS. This makes it much easier to understand the transformations that need to be made.
+
 ## Motivation
 
 **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.

No alert changes

Improved metrics

Total package byte prevSize

19182

increased by3.32%

Number of lines in readme file

142

increased by10.94%

No dependency changes