lvyjs-plugin-tailwindcss 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-present, Yuxi (Evan) You
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# lvyjs-plugin-tailwindcss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 LVY 的开发和构建流程中使用 Tailwind CSS 4。使用官方 `@tailwindcss/node` 编译器和 `@tailwindcss/oxide` 扫描器，通过 LVY 公开插件接口接入，无需配置 PostCSS。
+
+## 安装
+
+需要支持插件的 `lvyjs >= 0.3.0-alpha.6`、Tailwind CSS 4.3.3 或更新的 4.x，以及 Node.js 22.18+（22.x）或 24.11+。
+
+```sh
+npm install -D lvyjs lvyjs-plugin-tailwindcss tailwindcss@^4.3.3
+```
+
+本包尚未发布时，在仓库根目录运行 `yarn install`，然后在本包目录运行 `npm run build`。仓库的 workspace 会提供本包。
+
+## 使用
+
+```ts
+// lvy.config.ts
+import { defineConfig } from 'lvyjs'
+import tailwindcss from 'lvyjs-plugin-tailwindcss'
+
+export default defineConfig({
+  plugins: [tailwindcss()]
+})
+```
+
+```css
+/* src/style.css */
+@import 'tailwindcss';
+
+@theme {
+  --color-brand: #123456;
+}
+
+.card {
+  @apply flex rounded-lg;
+}
+```
+
+在入口中导入 CSS，得到生成的 CSS 文件的绝对路径：
+
+```ts
+import stylesheet from './style.css'
+import { readFile } from 'node:fs/promises'
+
+const css = await readFile(stylesheet, 'utf8')
+// 将 css 交给页面模板、服务端响应或你的渲染器。
+```
+
+这与 LVY 的资源导入约定一致。插件不负责把样式注入浏览器；开发时检测到源文件变化会重新生成 CSS 并重启应用，不提供 Vite 的浏览器 HMR。
+
+```sh
+lvy src/index.ts  # 开发
+lvy build         # 构建，默认压缩 CSS
+```
+
+支持相对路径、绝对路径、`file:` URL 和 LVY `alias.entries` 配置的 CSS 导入，也支持 CSS 内部的别名 `@import`。构建生成的 CSS 由 LVY `emitAsset` 写入资源目录，移动完整构建目录后，JavaScript 仍可定位 CSS。
+
+## 类名扫描与更新
+
+默认从项目根目录扫描源文件；构建输出目录和 `.lvy` 缓存目录会被排除，防止生成文件再次被扫描或触发重启。
+
+```ts
+plugins: [tailwindcss({ base: './src', exclude: ['coverage'] })]
+```
+
+使用 Tailwind 的 CSS 指令显式配置额外来源或关闭自动扫描：
+
+```css
+@import 'tailwindcss';
+@source "../templates";
+@source "../node_modules/my-ui";
+@source inline("underline font-bold");
+```
+
+```css
+@import 'tailwindcss' source(none);
+@source "../templates";
+```
+
+`@source` 路径相对于声明它的 CSS 文件。开发时监听扫描目录与编译依赖：修改类名、添加和删除源文件、修改被导入的 CSS 都会触发更新。每次编译使用新的编译器和扫描器，因此删除的类名不会残留在增量候选缓存中。这个选择优先保证正确性，大项目的重编译成本需要实际测量。
+
+类名需要完整出现在源文件中；运行时拼接出的类名应改为完整字符串或通过 `@source inline()` 注册。
+
+## 配置
+
+| 参数         | 默认值                    | 用途                                              |
+| ------------ | ------------------------- | ------------------------------------------------- |
+| `base`       | 项目根目录                | 自动扫描根目录，相对于 LVY 项目目录               |
+| `include`    | `/\.css$/`                | 要处理的 CSS 入口匹配规则                         |
+| `optimize`   | 开发 `false`，构建 `true` | 启用优化；也可传 `{ minify: false }` 只优化不压缩 |
+| `sourcemap`  | `false`                   | 在 CSS 中嵌入 source map                          |
+| `exclude`    | `[]`                      | 额外排除的目录，相对于 LVY 项目目录               |
+| `watchDelay` | `100`                     | 源文件变化后的重启防抖时间，单位毫秒              |
+
+支持普通 CSS、`@theme`、`@source`、`@apply` 和 Tailwind 官方编译器处理的 CSS 指令。无效指令会使构建失败，错误包含插件名 `lvy:tailwindcss`。
+
+本包处理 CSS，不编译 Sass/Less，也不提供 CSS Modules。`?raw`、`?url` 等导入交给其他插件。CSS 中图片、字体等 `url()` 引用不会由本包复制到构建目录；这些资源应使用可访问的 URL 或由应用另行部署。这里的构建目录可移动保证覆盖生成 CSS 文件本身。
+
+## 本包开发与验收
+
+```sh
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```
+
+测试使用临时项目运行真实 LVY CLI，覆盖开发更新、源文件新增与删除、CSS 依赖更新、构建 CSS 生成与目录移动、编译错误退出，以及 source(none)、内联来源和 source map。
+
+## 类型声明与 PostCSS 共存
+
+```ts
+// src/env.d.ts
+/// <reference types="lvyjs-plugin-tailwindcss/env" />
+```
+
+LVY 核心已移除内置样式处理。该插件独立提供 CSS 编译能力，不依赖 `lvyjs-plugin-postcss`。同一 CSS 入口由先匹配的插件接管，不会自动流经另一个插件；共存时明确区分入口：
+
+```ts
+plugins: [
+  tailwindcss({ include: /\.tailwind\.css$/ }),
+  postcss({ include: /\.postcss\.(css|scss|sass|less)$/ })
+]
+```
+
+同一入口需要额外 PostCSS 步骤时，改用 `lvyjs-plugin-postcss` 加官方 `@tailwindcss/postcss` 适配器，详见 [PostCSS 插件](../lvyjs-plugin-postcss/README.md)。这条路径的扫描与缓存行为由官方适配器管理。
+
+首次入口 CSS 编译失败后，修正该文件也可触发开发进程恢复；监听在编译开始前注册。
+
+同时使用两个插件时，只引用 `lvyjs-plugin-postcss/env`，它已包含 CSS、Sass/SCSS/Less 声明。无需同时引用两个插件的 `env`，以免产生重复的 CSS 默认导出声明。

package/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+  const path: string
+  export default path
+}

package/lib/index.d.ts

@@ -0,0 +1,21 @@
+import { LvyPlugin } from "lvyjs";
+//#region src/index.d.ts
+interface TailwindcssOptions {
+  /** Directory for automatic class detection. Defaults to the LVY project root. */
+  base?: string;
+  /** CSS entries handled by this plugin. Defaults to /\.css$/. */
+  include?: RegExp;
+  /** Optimize CSS. Defaults to true for builds and false during development. */
+  optimize?: boolean | {
+    minify?: boolean;
+  };
+  /** Embed a CSS source map. Defaults to false. */
+  sourcemap?: boolean;
+  /** Additional directories excluded from scanning and watching, relative to the project. */
+  exclude?: string[];
+  /** Debounce before requesting an application restart. Defaults to 100ms. */
+  watchDelay?: number;
+}
+declare function tailwindcss(options?: TailwindcssOptions): LvyPlugin;
+//#endregion
+export { TailwindcssOptions, tailwindcss as default, tailwindcss };

package/lib/index.js

@@ -0,0 +1,137 @@
+import { SourceWatcher, within } from "./watch.js";
+import { createHash } from "node:crypto";
+import { Features, compile, optimize, toSourceMap } from "@tailwindcss/node";
+import { clearRequireCache } from "@tailwindcss/node/require-cache";
+import { Scanner } from "@tailwindcss/oxide";
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/index.ts
+const prefix = "\0lvy-tailwindcss:";
+const posix = (path) => path.split(sep).join("/");
+function tailwindcss(options = {}) {
+	let env = {
+		cwd: process.cwd(),
+		command: "dev"
+	};
+	let base = env.cwd;
+	let aliases = [];
+	let excluded = [];
+	let watcher;
+	const dependenciesByEntry = /* @__PURE__ */ new Map();
+	const entries = /* @__PURE__ */ new Map();
+	const include = options.include ?? /\.css$/;
+	const applyAlias = (source) => {
+		const alias = aliases.find((alias) => source === alias.find || source.startsWith(alias.find + "/"));
+		return alias ? source.replace(alias.find, alias.replacement) : source;
+	};
+	const resolver = async (source, from) => {
+		const mapped = applyAlias(source);
+		return mapped === source ? void 0 : resolve(from, mapped);
+	};
+	const close = async () => {
+		await watcher?.close();
+		entries.clear();
+		dependenciesByEntry.clear();
+	};
+	return {
+		name: "lvy:tailwindcss",
+		enforce: "pre",
+		configResolved(config, environment) {
+			env = environment;
+			if (options.watchDelay !== void 0 && (!Number.isFinite(options.watchDelay) || options.watchDelay < 0)) throw new Error("watchDelay must be a nonnegative number");
+			base = resolve(env.cwd, options.base ?? ".");
+			aliases = config.alias ? config.alias.entries ?? [] : [];
+			const build = config.build && typeof config.build === "object" ? config.build : {};
+			const nativeOutput = build.tsdown && typeof build.tsdown === "object" ? build.tsdown.outDir : void 0;
+			excluded = [
+				...[build.dir ?? build.OutputOptions?.dir ?? "lib", ...typeof nativeOutput === "string" ? [nativeOutput] : []],
+				".lvy",
+				...options.exclude ?? []
+			].map((path) => resolve(env.cwd, path));
+			if (excluded.some((directory) => within(base, directory))) throw new Error("Tailwind source base must not be inside an excluded/output directory");
+		},
+		configureDev(context) {
+			watcher = new SourceWatcher(context, excluded, options.watchDelay ?? 100, (message) => console.warn(`[lvy:tailwindcss] ${message}`));
+			return close;
+		},
+		resolveId(source, importer) {
+			if (source.startsWith(prefix)) return source;
+			if (source.includes("?") || source.includes("#")) return null;
+			include.lastIndex = 0;
+			if (!include.test(source)) return null;
+			const mapped = applyAlias(source);
+			if (!isAbsolute(mapped) && !mapped.startsWith(".") && !mapped.startsWith("file:") && mapped === source) return null;
+			const path = mapped.startsWith("file:") ? fileURLToPath(mapped) : resolve(importer && isAbsolute(importer) ? dirname(importer) : env.cwd, mapped);
+			const id = prefix + createHash("sha256").update(path).digest("hex").slice(0, 24) + ".js";
+			entries.set(id, path);
+			return id;
+		},
+		async load(id) {
+			if (!id.startsWith(prefix)) return null;
+			const entry = entries.get(id);
+			if (!entry) return null;
+			if (this.command === "dev") await watcher?.watchFiles(entry, [entry]);
+			const input = await readFile(entry, "utf8");
+			clearRequireCache([...dependenciesByEntry.get(entry) ?? []]);
+			const files = /* @__PURE__ */ new Set([entry]);
+			const compiler = await compile(input, {
+				base: dirname(entry),
+				from: entry,
+				shouldRewriteUrls: true,
+				onDependency: (path) => files.add(resolve(path)),
+				customCssResolver: resolver,
+				customJsResolver: resolver
+			});
+			const sources = [
+				...compiler.root === "none" ? [] : compiler.root === null ? [{
+					base,
+					pattern: "**/*",
+					negated: false
+				}] : [{
+					...compiler.root,
+					negated: false
+				}],
+				...compiler.sources,
+				...excluded.map((directory) => ({
+					base: dirname(directory),
+					pattern: posix(basename(directory)) + "/**",
+					negated: true
+				}))
+			];
+			if (compiler.root && compiler.root !== "none") {
+				const root = resolve(compiler.root.base, compiler.root.pattern);
+				if (!(await stat(root)).isDirectory()) throw new Error(`Tailwind source() must point to a directory: ${root}`);
+			}
+			const scanner = new Scanner({ sources });
+			const candidates = compiler.features & Features.Utilities ? scanner.scan() : [];
+			for (const path of scanner.files) files.add(resolve(path));
+			dependenciesByEntry.set(entry, files);
+			if (this.command === "build") for (const file of files) this.addWatchFile(file);
+			else await watcher?.update(entry, {
+				files,
+				globs: scanner.globs
+			});
+			let css = compiler.build(candidates);
+			let map = options.sourcemap ? toSourceMap(compiler.buildSourceMap()).raw : void 0;
+			const optimization = options.optimize ?? this.command === "build";
+			if (optimization) {
+				const result = optimize(css, {
+					file: entry,
+					minify: typeof optimization === "object" ? optimization.minify ?? true : true,
+					map
+				});
+				css = result.code;
+				map = result.map;
+			}
+			if (map) css += "\n" + toSourceMap(map).comment(toSourceMap(map).inline);
+			return this.emitAsset({
+				name: basename(entry),
+				source: css
+			});
+		},
+		closeBundle: close
+	};
+}
+//#endregion
+export { tailwindcss as default, tailwindcss };

package/lib/watch.d.ts

@@ -0,0 +1,36 @@
+import { DevContext } from "lvyjs";
+//#region src/watch.d.ts
+type WatchSnapshot = {
+  files: Set<string>;
+  globs: {
+    base: string;
+    pattern: string;
+  }[];
+};
+declare const within: (path: string, directory: string) => boolean;
+/** Own the directory watch: LVY's literal file API cannot express filtered source globs. */
+declare class SourceWatcher {
+  private dev;
+  private excluded;
+  private delay;
+  private warn;
+  private watcher?;
+  private timer?;
+  private snapshots;
+  private matches;
+  private files;
+  private explicitModules;
+  private targets;
+  private ready?;
+  private closed;
+  private updates;
+  private settleReady?;
+  constructor(dev: DevContext, excluded: string[], delay: number, warn: (message: string) => void);
+  private ignored;
+  watchFiles(entry: string, files: Iterable<string>): Promise<void>;
+  update(entry: string, snapshot: WatchSnapshot): Promise<void>;
+  private updateSnapshot;
+  close(): Promise<void>;
+}
+//#endregion
+export { SourceWatcher, WatchSnapshot, within };

package/lib/watch.js

@@ -0,0 +1,122 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import chokidar from "chokidar";
+import picomatch from "picomatch";
+//#region src/watch.ts
+const within = (path, directory) => {
+	const part = relative(directory, path);
+	return part === "" || !part.startsWith(`..${sep}`) && part !== ".." && !isAbsolute(part);
+};
+const posix = (path) => path.split(sep).join("/");
+/** Own the directory watch: LVY's literal file API cannot express filtered source globs. */
+var SourceWatcher = class {
+	dev;
+	excluded;
+	delay;
+	warn;
+	watcher;
+	timer;
+	snapshots = /* @__PURE__ */ new Map();
+	matches = [];
+	files = /* @__PURE__ */ new Set();
+	explicitModules = [];
+	targets = /* @__PURE__ */ new Set();
+	ready;
+	closed = false;
+	updates = Promise.resolve();
+	settleReady;
+	constructor(dev, excluded, delay, warn) {
+		this.dev = dev;
+		this.excluded = excluded;
+		this.delay = delay;
+		this.warn = warn;
+	}
+	ignored = (input) => {
+		const path = resolve(input);
+		if (this.excluded.some((directory) => within(path, directory))) return true;
+		if (/(?:^|[\\/])(?:\.git|\.lvy)(?:[\\/]|$)/.test(path)) return true;
+		if (this.files.has(path)) return false;
+		if (/(?:^|[\\/])node_modules(?:[\\/]|$)/.test(path)) return !this.explicitModules.some((directory) => within(path, directory) || within(directory, path));
+		return false;
+	};
+	async watchFiles(entry, files) {
+		const previous = this.snapshots.get(entry);
+		await this.update(entry, {
+			files: /* @__PURE__ */ new Set([...previous?.files ?? [], ...files]),
+			globs: previous?.globs ?? []
+		});
+	}
+	update(entry, snapshot) {
+		const pending = this.updates.then(() => this.updateSnapshot(entry, snapshot));
+		this.updates = pending.catch(() => {});
+		return pending;
+	}
+	async updateSnapshot(entry, snapshot) {
+		if (this.closed) return;
+		this.snapshots.set(entry, snapshot);
+		this.files = new Set([...this.snapshots.values()].flatMap((value) => [...value.files]));
+		const globs = [...this.snapshots.values()].flatMap((value) => value.globs);
+		this.explicitModules = globs.filter((glob) => /(?:^|[\\/])node_modules(?:[\\/]|$)/.test(glob.base)).map((glob) => glob.base);
+		this.matches = globs.filter((glob) => !glob.pattern.startsWith("!")).map((glob) => {
+			const match = picomatch(glob.pattern, { dot: false });
+			return (path) => within(path, glob.base) && match(posix(relative(glob.base, path)));
+		});
+		const directories = globs.filter((glob) => !glob.pattern.startsWith("!")).map((glob) => glob.base);
+		const roots = [...new Set(directories)].filter((path) => !directories.some((parent) => parent !== path && within(path, parent)));
+		const targets = /* @__PURE__ */ new Set([...roots, ...[...this.files].filter((path) => {
+			return !(!/(?:^|[\\/])node_modules(?:[\\/]|$)/.test(path) || this.explicitModules.some((root) => within(path, root))) || !roots.some((root) => within(path, root));
+		})]);
+		const removed = [...this.targets].filter((path) => !targets.has(path));
+		const added = [...targets].filter((path) => !this.targets.has(path));
+		if (this.watcher && (removed.length || added.length)) {
+			await this.watcher.close();
+			this.watcher = void 0;
+			this.ready = void 0;
+		}
+		if (this.closed) return;
+		if (!this.watcher) {
+			this.watcher = chokidar.watch([...targets], {
+				ignoreInitial: true,
+				ignored: this.ignored
+			});
+			this.watcher.on("all", (event, path) => {
+				if (![
+					"add",
+					"change",
+					"unlink"
+				].includes(event) || this.ignored(path)) return;
+				const absolute = resolve(path);
+				if (!this.files.has(absolute) && !this.matches.some((match) => match(absolute))) return;
+				clearTimeout(this.timer);
+				this.timer = setTimeout(() => {
+					if (!this.closed) this.dev.restart();
+				}, this.delay);
+			});
+			this.watcher.on("error", (error) => this.warn(`Source watch failed: ${String(error)}`));
+			this.ready = new Promise((resolveReady, reject) => {
+				const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Tailwind source watch did not become ready")), 3e4);
+				this.settleReady = () => {
+					clearTimeout(timer);
+					resolveReady();
+				};
+				this.watcher.once("ready", this.settleReady);
+				this.watcher.once("error", (error) => {
+					clearTimeout(timer);
+					reject(error);
+				});
+			});
+		} else this.watcher.add([...targets].filter((path) => !this.targets.has(path)));
+		this.targets = targets;
+		await this.ready;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		clearTimeout(this.timer);
+		this.settleReady?.();
+		await this.updates;
+		await this.watcher?.close();
+		this.snapshots.clear();
+	}
+};
+//#endregion
+export { SourceWatcher, within };

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "lvyjs-plugin-tailwindcss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Tailwind CSS 4 integration for LVY development and builds",
+  "type": "module",
+  "license": "MIT",
+  "author": "lemonade",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./env": {
+      "types": "./env.d.ts"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE",
+    "env.d.ts"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.11.0"
+  },
+  "peerDependencies": {
+    "lvyjs": ">=0.3.0-alpha.6 <1",
+    "tailwindcss": "^4.3.3"
+  },
+  "dependencies": {
+    "@tailwindcss/node": "^4.3.3",
+    "@tailwindcss/oxide": "^4.3.3",
+    "chokidar": "^5.0.0",
+    "picomatch": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/picomatch": "^4.0.2",
+    "lvyjs": "0.3.0-alpha.6",
+    "tailwindcss": "^4.3.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lemonade-lab/lvyjs.git",
+    "directory": "packages/lvyjs-plugin-tailwindcss"
+  }
 }