tailwindcss-patch 7.1.6 → 8.0.0

package/README.md

@@ -1,121 +1,135 @@
 # tailwindcss-patch
 
-get tailwindcss context at runtime ! extract all classes into file!
+Modern tooling to patch Tailwind CSS, capture runtime contexts, and materialise every class that Tailwind can generate. The package now ships with a redesigned architecture focused on clarity, predictable configuration, and first-class Tailwind v4 support.
 
-- [tailwindcss-patch](#tailwindcss-patch)
-  - [Docs](#docs)
-  - [Setup](#setup)
-  - [Usage](#usage)
-  - [Cli](#cli)
-    - [Extract all class into a json](#extract-all-class-into-a-json)
-  - [Nodejs API](#nodejs-api)
-  - [Config](#config)
-    - [Init Config File](#init-config-file)
-  - [What's next?](#whats-next)
+- Export runtime contexts for Tailwind v2/v3 without editing source files manually.
+- Traverse Tailwind v4 projects by scanning CSS outputs and content sources.
+- Write class inventories to disk or keep them in memory for tooling integrations.
+- Control caching, filtering, and custom unit extensions from a single, typed entrypoint.
 
-> Nodejs version should >= `16.6.0`
+## Installation
 
-## Docs
-
-[mangle.icebreaker.top](https://mangle.icebreaker.top)
-
-## Setup
-
-1. Install package
-
-```sh
-<yarn|npm|pnpm> add -D tailwindcss-patch
-```
-
-2. Patch tailwindcss
-
-```sh
-npx tw-patch install
+```bash
+pnpm add -D tailwindcss-patch
+pnpm dlx tw-patch install
 ```
 
-3. Add `prepare` script (keeps patch persisted after npm install)
-
-`package.json`
+Keep the patch applied after installs by adding a `prepare` hook:
 
 ```json
 {
-  /* ... */
   "scripts": {
     "prepare": "tw-patch install"
   }
 }
 ```
 
-## Usage
+## CLI Usage
 
-## Cli
+Run the CLI through `tw-patch` (or `tailwindcss-patch`) from your project root.
 
-### Extract all class into a json
+```bash
+# Apply runtime patches to the local Tailwind installation
+pnpm dlx tw-patch install
 
-```sh
-npx tw-patch extract
+# Extract all classes into the configured output file
+pnpm dlx tw-patch extract
 ```
 
-default there will be a json in `.tw-patch/tw-class-list.json` in your project.
-
-you can custom this behavior by config `tailwindcss-mangle.config.ts`
+### Extract options
 
-## Nodejs API
+| Flag                     | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| `--cwd <dir>`            | Use a different working directory when loading configuration.    |
+| `--output <file>`        | Override the target file for the generated class list.           |
+| `--format <json\|lines>` | Switch between JSON output (default) and newline-delimited text. |
+| `--css <file>`           | Provide a CSS entry file when working with Tailwind v4 projects. |
+| `--no-write`             | Skip writing to disk and only return the collected classes.      |
 
-```js
-import { TailwindcssPatcher } from 'tailwindcss-patch'
+The CLI loads `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Legacy configs continue to work; see the [migration guide](./MIGRATION.md) for hints on the new fields.
 
-const twPatcher = new TailwindcssPatcher(/* options */)
-// do patch
-twPatcher.patch()
-// get all contexts at runtime
-twPatcher.getContexts()
-// get all class generated by tailwindcss utilities
-twPatcher.getClassSet()
-```
+## Programmatic API
 
-## Config
+```ts
+import { TailwindcssPatcher } from 'tailwindcss-patch'
 
-### Init Config File
+const patcher = new TailwindcssPatcher({
+  overwrite: true,
+  cache: {
+    enabled: true,
+    dir: '.tw-patch/cache',
+    strategy: 'merge',
+  },
+  output: {
+    file: '.tw-patch/tw-class-list.json',
+    format: 'json',
+  },
+  features: {
+    exposeContext: { refProperty: 'runtimeContexts' },
+    extendLengthUnits: {
+      units: ['rpx'],
+    },
+  },
+  tailwind: {
+    version: 4,
+    v4: {
+      base: './src',
+      cssEntries: ['dist/tailwind.css'],
+    },
+  },
+})
 
-```sh
-npx tw-patch init
+await patcher.patch()
+const { classList, filename } = await patcher.extract()
 ```
 
-Then there will be a ts file called `tailwindcss-mangle.config.ts` exist in your `cwd`.
+The constructor accepts either the new object shown above or the historical `patch`/`cache` shape. Conversions happen internally so existing configs remain backwards compatible.
 
-The config as follows:
+### Helper utilities
 
-```ts
-import { defineConfig } from 'tailwindcss-patch'
+- `normalizeOptions` – normalise raw user input to the runtime shape.
+- `CacheStore` – read/write class caches respecting merge or overwrite semantics.
+- `extractValidCandidates` – scan Tailwind v4 CSS/content sources with the Tailwind Oxide scanner.
+- `runTailwindBuild` – run the Tailwind PostCSS plugin for v2/v3 projects to prime runtime contexts.
 
-export default defineConfig({})
-```
+All helpers are exported from the package root for direct consumption in custom tooling.
 
-you can custom `tw-patch` behavior by `patch` option:
+## Configuration Example
 
 ```ts
+// tailwindcss-patch.config.ts
 import { defineConfig } from 'tailwindcss-patch'
 
 export default defineConfig({
   patch: {
     output: {
-      filename: 'xxx.json',
-      loose: true,
-      removeUniversalSelector: true
+      filename: '.tw-patch/tw-class-list.json',
+      removeUniversalSelector: true,
+      format: 'json',
     },
     tailwindcss: {
-      config: 'path/to/your-tailwind.config.js',
-      cwd: 'project/cwd'
-    }
-  }
+      version: 4,
+      v4: {
+        cssEntries: ['dist/tailwind.css'],
+        sources: [{ base: 'src', pattern: '**/*.{html,tsx}', negated: false }],
+      },
+    },
+    applyPatches: {
+      exportContext: true,
+      extendLengthUnits: {
+        units: ['rpx'],
+      },
+    },
+  },
 })
 ```
 
-## What's next?
+Even though `defineConfig` still exposes the historical shape, every new option is supported and will be normalised automatically.
+
+## Migration
 
-At the moment I just extracted all the tool classes to actually get the context of `tailwindcss` to analyze. You can add more functionality to this project by giving me `issue` or `pr`.
+Breaking changes, module moves, and upgrade paths are documented in [MIGRATION.md](./MIGRATION.md). Review it when updating from tailwindcss-patch v7.x or earlier.
 
-Of course, the extracted `JSON` isn't just for you to look at. You can analyze it, and I use it as a data file for my `tailwindcss-mangle`.
+## License
 
-The `tailwindcss-mangle` itself is an obfuscation tool to obfuscate the tools generated by `tailwindcss`, see the next article for more details on how to use it.
+MIT © ice breaker