cls-extended 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# @cls-extended/core
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+
+Zero-runtime Tailwind CSS responsive class transformer. Write cleaner responsive syntax that compiles to standard Tailwind classes at build time.
+
+## Features
+
+- ⚡ **Zero Runtime Overhead** - All transformations happen at build time
+- 🎨 **Better DX** - Cleaner, more maintainable responsive class syntax
+- 🔧 **Universal** - Works with Vite, Webpack, Rollup, esbuild, Rspack, Rolldown, and Farm
+- 📦 **Tiny Bundle** - ~8KB total, 0KB runtime impact
+- 🔒 **Type Safe** - Full TypeScript support
+
+## Installation
+
+```bash
+npm i -D @cls-extended/core
+```
+
+## Usage
+
+### Setup Plugin
+
+<details>
+<summary>Vite</summary><br>
+
+```ts
+// vite.config.ts
+import clsExtended from '@cls-extended/core/adapters/vite'
+
+export default defineConfig({
+  plugins: [clsExtended()],
+})
+```
+
+</details>
+
+<details>
+<summary>Webpack</summary><br>
+
+```js
+// webpack.config.js
+import clsExtended from '@cls-extended/core/adapters/webpack'
+
+export default {
+  plugins: [clsExtended()],
+}
+```
+
+</details>
+
+<details>
+<summary>Rollup</summary><br>
+
+```ts
+// rollup.config.js
+import clsExtended from '@cls-extended/core/adapters/rollup'
+
+export default {
+  plugins: [clsExtended()],
+}
+```
+
+</details>
+
+<details>
+<summary>esbuild</summary><br>
+
+```ts
+import { build } from 'esbuild'
+import clsExtended from '@cls-extended/core/adapters/esbuild'
+
+build({
+  plugins: [clsExtended()],
+})
+```
+
+</details>
+
+<details>
+<summary>Rspack</summary><br>
+
+```ts
+// rspack.config.js
+import clsExtended from '@cls-extended/core/adapters/rspack'
+
+export default {
+  plugins: [clsExtended()],
+}
+```
+
+</details>
+
+### In Your Components
+
+```tsx
+import { cls } from '@cls-extended/core/api'
+
+function Component() {
+  return (
+    <div className={cls('text-xl font-bold', { 
+      md: 'text-2xl', 
+      lg: 'text-3xl' 
+    })}>
+      Responsive Text
+    </div>
+  )
+}
+```
+
+**Compiles to:**
+
+```tsx
+<div className="text-xl font-bold md:text-2xl lg:text-3xl">
+  Responsive Text
+</div>
+```
+
+## API
+
+### `cls(baseClasses, responsiveClasses?)`
+
+Transform responsive Tailwind classes at build time.
+
+**Parameters:**
+- `baseClasses` (string) - Base Tailwind classes
+- `responsiveClasses` (object, optional) - Responsive breakpoint classes
+
+**Supported Breakpoints:**
+- `sm` - 640px
+- `md` - 768px
+- `lg` - 1024px
+- `xl` - 1280px
+- `2xl` - 1536px
+
+**Example:**
+
+```ts
+cls('p-4 bg-white', { 
+  md: 'p-6', 
+  lg: 'p-8 shadow-lg' 
+})
+// → "p-4 bg-white md:p-6 lg:p-8 lg:shadow-lg"
+```
+
+## How It Works
+
+1. **Build Time**: Plugin scans your code for `cls()` calls
+2. **AST Transform**: Parses and transforms the syntax using Babel
+3. **Output**: Generates standard Tailwind classes with zero runtime code
+
+## License
+
+[MIT](./LICENSE) License © 2025 [Yeasin](https://github.com/yeasin2002)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@cls-extended/core.svg
+[npm-version-href]: https://npmjs.com/package/@cls-extended/core
+[npm-downloads-src]: https://img.shields.io/npm/dm/@cls-extended/core
+[npm-downloads-href]: https://www.npmcharts.com/compare/@cls-extended/core?interval=30

package/dist/adapters/vite.d.ts

@@ -0,0 +1,7 @@
+import { Options } from "../core/options.js";
+import { UnpluginInstance } from "unplugin";
+
+//#region src/adapters/vite.d.ts
+declare const vitePlugin: UnpluginInstance<Options | undefined, false>["vite"];
+//#endregion
+export { vitePlugin as default };

package/dist/adapters/vite.js

@@ -0,0 +1,7 @@
+import unplugin from "../index.js";
+
+//#region src/adapters/vite.ts
+const vitePlugin = unplugin.vite;
+
+//#endregion
+export { vitePlugin as default };

package/dist/adapters/webpack.d.ts

@@ -0,0 +1,6 @@
+import unplugin from "../index.js";
+
+//#region src/adapters/webpack.d.ts
+declare const _default: typeof unplugin.webpack;
+//#endregion
+export { _default as default };

package/dist/adapters/webpack.js

@@ -0,0 +1,7 @@
+import unplugin from "../index.js";
+
+//#region src/adapters/webpack.ts
+var webpack_default = unplugin.webpack;
+
+//#endregion
+export { webpack_default as default };

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+//#region src/api.d.ts
+type ResponsiveBreakpoint = "sm" | "md" | "lg" | "xl" | "2xl";
+type ResponsiveClasses = Partial<Record<ResponsiveBreakpoint, string>>;
+/**
+ * Transform responsive Tailwind classes at build time
+ *
+ * @example
+ * tw('text-xl font-bold', { md: 'text-2xl', lg: 'text-3xl' })
+ * // Compiles to: "text-xl font-bold md:text-2xl lg:text-3xl"
+ */
+declare function cls(baseClasses: string, responsiveClasses?: ResponsiveClasses): string;
+//#endregion
+export { ResponsiveBreakpoint, ResponsiveClasses, cls };

package/dist/api.js

@@ -0,0 +1,20 @@
+//#region src/api.ts
+/**
+* Transform responsive Tailwind classes at build time
+*
+* @example
+* tw('text-xl font-bold', { md: 'text-2xl', lg: 'text-3xl' })
+* // Compiles to: "text-xl font-bold md:text-2xl lg:text-3xl"
+*/
+function cls(baseClasses, responsiveClasses) {
+	if (!responsiveClasses) return baseClasses;
+	const parts = [baseClasses];
+	for (const [breakpoint, classes] of Object.entries(responsiveClasses)) {
+		const prefixed = classes.split(/\s+/).filter(Boolean).map((cls) => `${breakpoint}:${cls}`).join(" ");
+		parts.push(prefixed);
+	}
+	return parts.join(" ");
+}
+
+//#endregion
+export { cls };

package/dist/core/options.d.ts

@@ -0,0 +1,34 @@
+import { FilterPattern } from "unplugin";
+
+//#region src/core/options.d.ts
+interface Options {
+  /**
+   * Files to include in processing
+   * @default [/\.[jt]sx?$/]
+   */
+  include?: FilterPattern;
+  /**
+   * Files to exclude from processing
+   * @default [/node_modules/]
+   */
+  exclude?: FilterPattern;
+  /**
+   * Enable source map generation
+   * @default true
+   */
+  sourcemap?: boolean;
+  /**
+   * Custom Tailwind breakpoints
+   * @default { sm: '640px', md: '768px', lg: '1024px', xl: '1280px', '2xl': '1536px' }
+   */
+  breakpoints?: Record<string, string>;
+  /**
+   * Enable additional variant support (hover, focus, dark, etc.)
+   * @default false
+   */
+  enableVariants?: boolean;
+}
+type OptionsResolved = Required<Options>;
+declare function resolveOptions(options?: Options): OptionsResolved;
+//#endregion
+export { Options, OptionsResolved, resolveOptions };

package/dist/core/options.js

@@ -0,0 +1,19 @@
+//#region src/core/options.ts
+function resolveOptions(options = {}) {
+	return {
+		include: options.include ?? [/\.[jt]sx?$/],
+		exclude: options.exclude ?? [/node_modules/],
+		sourcemap: options.sourcemap ?? true,
+		breakpoints: options.breakpoints ?? {
+			sm: "640px",
+			md: "768px",
+			lg: "1024px",
+			xl: "1280px",
+			"2xl": "1536px"
+		},
+		enableVariants: options.enableVariants ?? false
+	};
+}
+
+//#endregion
+export { resolveOptions };

package/dist/core/parser.d.ts

@@ -0,0 +1,10 @@
+//#region src/core/parser.d.ts
+interface ClsCallExpression {
+  baseClasses: string;
+  responsiveClasses: Record<string, string>;
+  start: number;
+  end: number;
+}
+declare function findClsCalls(code: string): ClsCallExpression[];
+//#endregion
+export { ClsCallExpression, findClsCalls };

package/dist/core/parser.js

@@ -0,0 +1,57 @@
+import { parse } from "@babel/parser";
+
+//#region src/core/parser.ts
+function findClsCalls(code) {
+	let ast;
+	try {
+		ast = parse(code, {
+			sourceType: "module",
+			plugins: ["jsx", "typescript"]
+		});
+	} catch {
+		return [];
+	}
+	const clsCalls = [];
+	function traverse(node) {
+		if (!node || typeof node !== "object") return;
+		if (node.type === "CallExpression") {
+			const callee = node.callee;
+			if (callee.type === "Identifier" && callee.name === "tw" || callee.type === "MemberExpression" && callee.object.type === "Identifier" && callee.object.name === "tw") {
+				const args = node.arguments;
+				if (args.length === 0) return;
+				const baseArg = args[0];
+				if (baseArg.type !== "StringLiteral") return;
+				const baseClasses = baseArg.value;
+				const responsiveClasses = {};
+				if (args.length > 1) {
+					const responsiveArg = args[1];
+					if (responsiveArg.type === "ObjectExpression") {
+						for (const prop of responsiveArg.properties) if (prop.type === "ObjectProperty" && prop.value.type === "StringLiteral") {
+							let key;
+							if (prop.key.type === "Identifier") key = prop.key.name;
+							else if (prop.key.type === "StringLiteral") key = prop.key.value;
+							if (key) responsiveClasses[key] = prop.value.value;
+						}
+					}
+				}
+				clsCalls.push({
+					baseClasses,
+					responsiveClasses,
+					start: node.start,
+					end: node.end
+				});
+			}
+		}
+		for (const key in node) {
+			if (key === "loc" || key === "range" || key === "tokens") continue;
+			const value = node[key];
+			if (Array.isArray(value)) for (const item of value) traverse(item);
+			else if (value && typeof value === "object") traverse(value);
+		}
+	}
+	traverse(ast);
+	return clsCalls;
+}
+
+//#endregion
+export { findClsCalls };

package/dist/core/transform.d.ts

@@ -0,0 +1,10 @@
+import { OptionsResolved } from "./options.js";
+
+//#region src/core/transform.d.ts
+interface TransformResult {
+  code: string;
+  map: any;
+}
+declare function transformClsCalls(code: string, _id: string, options: OptionsResolved): TransformResult | null;
+//#endregion
+export { TransformResult, transformClsCalls };

package/dist/core/transform.js

@@ -0,0 +1,33 @@
+import { findClsCalls } from "./parser.js";
+import MagicString from "magic-string";
+
+//#region src/core/transform.ts
+function transformClsCalls(code, _id, options) {
+	const twCalls = findClsCalls(code);
+	if (twCalls.length === 0) return null;
+	const s = new MagicString(code);
+	for (const call of twCalls) {
+		const transformedString = generateClassString(call, options);
+		s.overwrite(call.start, call.end, `"${transformedString}"`);
+	}
+	return {
+		code: s.toString(),
+		map: options.sourcemap ? s.generateMap({ hires: true }) : null
+	};
+}
+function generateClassString(call, options) {
+	const { baseClasses, responsiveClasses } = call;
+	const parts = [baseClasses];
+	for (const [breakpoint, classes] of Object.entries(responsiveClasses)) {
+		if (!options.breakpoints[breakpoint] && !options.enableVariants) {
+			console.warn(`Unknown breakpoint: ${breakpoint}`);
+			continue;
+		}
+		const prefixedClasses = classes.split(/\s+/).filter(Boolean).map((cls) => `${breakpoint}:${cls}`).join(" ");
+		parts.push(prefixedClasses);
+	}
+	return parts.filter(Boolean).join(" ");
+}
+
+//#endregion
+export { transformClsCalls };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Options } from "./core/options.js";
+import { UnpluginInstance } from "unplugin";
+
+//#region src/index.d.ts
+declare const unplugin: UnpluginInstance<Options | undefined, false>;
+//#endregion
+export { type Options, unplugin as default };

package/dist/index.js

@@ -0,0 +1,24 @@
+import { resolveOptions } from "./core/options.js";
+import { transformClsCalls } from "./core/transform.js";
+import { createUnplugin } from "unplugin";
+
+//#region src/index.ts
+const unplugin = createUnplugin((rawOptions = {}) => {
+	const options = resolveOptions(rawOptions);
+	return {
+		name: "cls-extended",
+		transform: {
+			filter: { id: {
+				include: options.include,
+				exclude: options.exclude
+			} },
+			handler(code, id) {
+				if (!code.includes("tw(")) return null;
+				return transformClsCalls(code, id, options);
+			}
+		}
+	};
+});
+
+//#endregion
+export { unplugin as default };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "cls-extended",
+  "type": "module",
+  "version": "1.0.0",
+  "exports": {
+    ".": "./dist/index.js",
+    "./adapters/vite": "./dist/adapters/vite.js",
+    "./adapters/webpack": "./dist/adapters/webpack.js",
+    "./api": "./dist/api.js",
+    "./core/options": "./dist/core/options.js",
+    "./core/parser": "./dist/core/parser.js",
+    "./core/transform": "./dist/core/transform.js",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*.d.ts",
+        "./*"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "lint": "eslint --cache .",
+    "lint:fix": "pnpm run lint --fix",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.0",
+    "magic-string": "^0.30.21",
+    "unplugin": "^3.0.0"
+  },
+  "devDependencies": {
+    "@babel/types": "^7.29.0",
+    "@eslint/js": "^9.39.2",
+    "@sxzz/eslint-config": "^7.6.0",
+    "@sxzz/prettier-config": "^2.3.1",
+    "@sxzz/test-utils": "^0.5.15",
+    "@types/node": "^25.2.0",
+    "bumpp": "^10.4.0",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.20.1",
+    "tsdown-preset-sxzz": "^0.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "unplugin",
+    "vite",
+    "webpack",
+    "rspack",
+    "rollup",
+    "rolldown",
+    "esbuild",
+    "farm"
+  ]
+}