From 3839c78965d681648227fc72a6235602ee09eef0 Mon Sep 17 00:00:00 2001 From: gaurav0107 Date: Fri, 5 Jun 2026 08:48:07 +0530 Subject: [PATCH] docs: add JSDoc to @fresh/plugin-tailwind public symbols Documents the `tailwind()` plugin function and `TailwindPluginOptions` interface so the package surfaces in JSR with examples and `@param` descriptions instead of the current 0% documented status. Also corrects the README's `Basic Usage` and `Option Configuration` snippets, which called `tailwind(builder, app, ...)` even though the function signature only takes `(builder, options)`, and dropped a `base: null` example that did not match the `base?: string` type. Refs #3596 --- packages/plugin-tailwindcss/README.md | 7 +-- packages/plugin-tailwindcss/src/mod.ts | 63 ++++++++++++++++++++++++ packages/plugin-tailwindcss/src/types.ts | 35 ++++++++++--- 3 files changed, 94 insertions(+), 11 deletions(-) diff --git a/packages/plugin-tailwindcss/README.md b/packages/plugin-tailwindcss/README.md index e7ef8257761..b842399a1ed 100644 --- a/packages/plugin-tailwindcss/README.md +++ b/packages/plugin-tailwindcss/README.md @@ -11,7 +11,7 @@ import { app } from "./main.ts"; import { tailwind } from "@fresh/plugin-tailwind"; const builder = new Builder(); -tailwind(builder, app); +tailwind(builder); if (Deno.args.includes("build")) { builder.build(app); @@ -29,15 +29,12 @@ import { app } from "./main.ts"; import { tailwind } from "@fresh/plugin-tailwind"; const builder = new Builder(); -tailwind(builder, app, { +tailwind(builder, { // Exclude certain files from processing exclude: ["/admin/**", "*.temp.css"], // Force optimization (defaults to production mode) optimize: true, - - // Exclude base styles - base: null, }); if (Deno.args.includes("build")) { diff --git a/packages/plugin-tailwindcss/src/mod.ts b/packages/plugin-tailwindcss/src/mod.ts index 6db172a80b5..097570e0859 100644 --- a/packages/plugin-tailwindcss/src/mod.ts +++ b/packages/plugin-tailwindcss/src/mod.ts @@ -1,3 +1,30 @@ +/** + * Tailwind CSS v4 plugin for Fresh. + * + * Registers a static-file transform on the supplied {@linkcode Builder} that + * runs `.css` files through `@tailwindcss/postcss`. CSS is optimized + * automatically when Fresh is in production mode. + * + * @example + * ```ts + * // dev.ts + * import { Builder } from "fresh/dev"; + * import { app } from "./main.ts"; + * import { tailwind } from "@fresh/plugin-tailwind"; + * + * const builder = new Builder(); + * tailwind(builder); + * + * if (Deno.args.includes("build")) { + * await builder.build(app); + * } else { + * await builder.listen(app); + * } + * ``` + * + * @module + */ + import type { Builder } from "fresh/dev"; import twPostcss from "@tailwindcss/postcss"; import postcss from "postcss"; @@ -6,6 +33,42 @@ import type { TailwindPluginOptions } from "./types.ts"; // Re-export types for public API export type { TailwindPluginOptions } from "./types.ts"; +/** + * Register the Tailwind CSS v4 transform on a Fresh {@linkcode Builder}. + * + * The plugin attaches a `.css` static-file transform that processes stylesheets + * with `@tailwindcss/postcss`. When `builder.config.mode === "production"` the + * default `optimize` setting is `true`; in development it is `false`. Either + * default can be overridden via `options.optimize`. + * + * Files matched by `options.exclude` are passed through untouched, which is + * useful for routes or partials that ship their own CSS. + * + * @param builder The Fresh dev builder to attach the transform to. + * @param options Optional Tailwind and exclusion settings. See + * {@linkcode TailwindPluginOptions}. + * + * @example Basic usage + * ```ts + * import { Builder } from "fresh/dev"; + * import { tailwind } from "@fresh/plugin-tailwind"; + * + * const builder = new Builder(); + * tailwind(builder); + * ``` + * + * @example Customize options + * ```ts + * import { Builder } from "fresh/dev"; + * import { tailwind } from "@fresh/plugin-tailwind"; + * + * const builder = new Builder(); + * tailwind(builder, { + * exclude: ["/admin/**", "*.temp.css"], + * optimize: { minify: true }, + * }); + * ``` + */ export function tailwind( builder: Builder, options: TailwindPluginOptions = {}, diff --git a/packages/plugin-tailwindcss/src/types.ts b/packages/plugin-tailwindcss/src/types.ts index 677e7b270d2..729f06cb773 100644 --- a/packages/plugin-tailwindcss/src/types.ts +++ b/packages/plugin-tailwindcss/src/types.ts @@ -1,22 +1,45 @@ import type { OnTransformOptions } from "fresh/dev"; -// based on the original code, this type is used to define options for the Tailwind plugin +/** + * Internal option shape forwarded to `@tailwindcss/postcss`. Consumers should + * use {@linkcode TailwindPluginOptions} instead. + */ type PluginOptions = { /** - * Base CSS to be included. Set to null to exclude base styles. + * Base CSS to be included. Set to `null` to exclude base styles. */ base?: string; /** - * Enable or disable CSS optimization. Defaults to true if Fresh is in production mode and false otherwise. - * Can be a boolean or an object with minify options. - * @default app.config.mode === "production" + * Enable or disable CSS optimization. Defaults to `true` when Fresh is + * running in production mode and `false` otherwise. Pass an object to + * fine-tune minification behavior. + * + * @default {builder.config.mode === "production"} */ optimize?: boolean | { minify?: boolean; }; }; +/** + * Options accepted by the {@linkcode tailwind} plugin. + * + * @example Exclude an admin route and force optimization + * ```ts + * import { Builder } from "fresh/dev"; + * import { tailwind } from "@fresh/plugin-tailwind"; + * + * const builder = new Builder(); + * tailwind(builder, { + * exclude: ["/admin/**", "*.temp.css"], + * optimize: true, + * }); + * ``` + */ export interface TailwindPluginOptions extends PluginOptions { - /** Exclude paths or globs that should not be processed */ + /** + * Paths or glob patterns that should be skipped by the Tailwind transform. + * Forwarded to {@linkcode Builder.onTransformStaticFile}. + */ exclude?: OnTransformOptions["exclude"]; }