@fullhuman/purgecss-from-tsx 7.0.2 → 9.0.0

package/README.md

@@ -1,11 +1,139 @@
-# `purgecss-from-tsx`
+# @fullhuman/purgecss-from-tsx
 
-> TODO: description
+[![npm version](https://img.shields.io/npm/v/@fullhuman/purgecss-from-tsx.svg)](https://www.npmjs.com/package/@fullhuman/purgecss-from-tsx)
+
+TSX extractor for [PurgeCSS](https://purgecss.com). This extractor parses TSX files (TypeScript + JSX) and extracts used selectors from component names, `className`, and `id` attributes.
+
+## Installation
+
+```bash
+npm install @fullhuman/purgecss-from-tsx --save-dev
+```
 
 ## Usage
 
+### With PurgeCSS
+
+```js
+import { PurgeCSS } from "purgecss";
+import purgeFromTsx from "@fullhuman/purgecss-from-tsx";
+
+const result = await new PurgeCSS().purge({
+  content: ["**/*.tsx"],
+  css: ["**/*.css"],
+  extractors: [
+    {
+      extractor: purgeFromTsx(),
+      extensions: ["tsx"],
+    },
+  ],
+});
+```
+
+### With Custom Options
+
+You can pass custom options for both the TypeScript compiler and the acorn parser:
+
+```js
+import purgeFromTsx from "@fullhuman/purgecss-from-tsx";
+
+const extractor = purgeFromTsx({
+  // Acorn parser options
+  acornOptions: {
+    ecmaVersion: 2020,
+    sourceType: "module",
+  },
+  // TypeScript compiler options
+  tsOptions: {
+    target: ts.ScriptTarget.ES2020,
+  },
+});
 ```
-const purgecssFromTsx = require('purgecss-from-tsx');
 
-// TODO: DEMONSTRATE API
+### Standalone
+
+You can use the extractor standalone to extract selectors from TSX content:
+
+```js
+import purgeFromTsx from "@fullhuman/purgecss-from-tsx";
+
+const tsx = `
+  interface Props {
+    title: string;
+  }
+  
+  function Card({ title }: Props): JSX.Element {
+    return (
+      <div className="card">
+        <h2 id="card-title" className="card-title">{title}</h2>
+        <Button className="btn btn-primary" />
+      </div>
+    );
+  }
+`;
+
+const selectors = purgeFromTsx()(tsx);
+
+console.log(selectors);
+// ["div", "card", "h2", "card-title", "card-title", "Button", "btn", "btn-primary"]
 ```
+
+## API
+
+### `purgeFromTsx(options?: Options): (content: string) => string[]`
+
+Creates an extractor function for TSX content.
+
+#### Parameters
+
+- `options` (optional) - Configuration object with:
+  - `acornOptions` - [Acorn parser options](https://github.com/acornjs/acorn#interface). Defaults to `{ ecmaVersion: "latest" }`
+  - `tsOptions` - [TypeScript compiler options](https://www.typescriptlang.org/tsconfig). JSX is always preserved for parsing.
+
+#### Returns
+
+A function that takes TSX content as a string and returns an array of selectors.
+
+## How It Works
+
+This extractor works in two steps:
+
+1. **TypeScript Transpilation** - Uses the TypeScript compiler to transpile TSX to JSX, stripping type annotations while preserving JSX syntax
+2. **JSX Extraction** - Uses [@fullhuman/purgecss-from-jsx](https://www.npmjs.com/package/@fullhuman/purgecss-from-jsx) to extract selectors from the resulting JSX
+
+## What It Extracts
+
+The extractor parses TSX and extracts:
+
+1. **Component names** - JSX element names (e.g., `div`, `Header`, `MyComponent`), including elements inside the value of another attribute (e.g., `icon={<Icon />}`)
+2. **className values** - String values from `className` attributes, split by whitespace
+3. **id values** - String values from `id` attributes
+
+When `className` or `id` is an expression, its static parts are extracted the same way as by the [JSX extractor](https://github.com/FullHuman/purgecss/tree/main/packages/purgecss-from-jsx#what-it-extracts): for example, `className={active ? "on" : "off"}` gives `on` and `off`, and ``className={`card ${size}`}`` gives `card`. The TypeScript syntax is stripped first, so `className={"card" as string}` gives `card`.
+
+### Example
+
+```tsx
+interface CardProps {
+  variant: "primary" | "secondary";
+}
+
+const Card: React.FC<CardProps> = ({ variant }) => (
+  <article className="card card-hover" id="featured">
+    <CardHeader className="p-4" />
+    <CardBody />
+  </article>
+);
+```
+
+Extracted selectors: `["article", "card", "card-hover", "featured", "CardHeader", "p-4", "CardBody"]`
+
+## Limitations
+
+- Only extracts static string values from `className` and `id`
+- Values computed at runtime, like `className={styles.container}` or the `size` of ``className={`btn-${size}`}``, are not extracted
+- For dynamic class names, consider using PurgeCSS's [safelist](https://purgecss.com/safelisting.html) option
+
+## License
+
+MIT License

package/lib/purgecss-from-tsx.esm.js

@@ -14,6 +14,7 @@ function purgeFromTsx(options) {
         return purgeFromJsx(options === null || options === void 0 ? void 0 : options.acornOptions)(ts.transpileModule(content, {
             compilerOptions: {
                 jsx: ts.JsxEmit.Preserve,
+                module: ts.ModuleKind.CommonJS,
                 ...options === null || options === void 0 ? void 0 : options.tsOptions,
             },
         }).outputText);

package/lib/purgecss-from-tsx.js

@@ -35,6 +35,7 @@ function purgeFromTsx(options) {
         return purgeFromJsx(options === null || options === void 0 ? void 0 : options.acornOptions)(ts__namespace.transpileModule(content, {
             compilerOptions: {
                 jsx: ts__namespace.JsxEmit.Preserve,
+                module: ts__namespace.ModuleKind.CommonJS,
                 ...options === null || options === void 0 ? void 0 : options.tsOptions,
             },
         }).outputText);

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@fullhuman/purgecss-from-tsx",
-  "version": "7.0.2",
+  "version": "9.0.0",
   "description": "TSX extractor for PurgeCSS",
   "author": "Ffloriel",
   "homepage": "https://github.com/FullHuman/purgecss#readme",
-  "license": "ISC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "main": "./lib/purgecss-from-tsx.js",
   "module": "./lib/purgecss-from-tsx.esm.js",
   "types": "./lib/purgecss-from-tsx.d.ts",
@@ -19,21 +22,20 @@
     "type": "git",
     "url": "git+https://github.com/FullHuman/purgecss.git"
   },
-  "scripts": {
-    "build": "ts-node build.ts",
-    "test": "jest"
-  },
   "bugs": {
     "url": "https://github.com/FullHuman/purgecss/issues"
   },
   "dependencies": {
-    "@fullhuman/purgecss-from-jsx": "^7.0.2",
-    "acorn": "^8.7.0",
-    "typescript": "^5.6.2"
+    "@fullhuman/purgecss-from-jsx": "^9.0.0",
+    "acorn": "^8.19.0",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "e95398d961e03a809b5e3da75e3dae1813b46b68"
-}
+  "scripts": {
+    "build": "ts-node build.ts",
+    "test": "jest"
+  }
+}