chore: deprecate legacy Builder API (#3635)

Adds @deprecated JSDoc tags to all public exports in:
- @fresh/core/dev (Builder, BuildOptions, ResolvedBuildConfig, etc.)
- @fresh/plugin-tailwind (tailwind function, TailwindPluginOptions)
- @fresh/plugin-tailwind-v3 (all exports)

Also marks the --builder flag in @fresh/init as deprecated in help
text and prints a warning when it's used.

Closes #3635

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bartlomieju

packages/fresh/src/dev/builder.ts

@@ -109,6 +109,10 @@ export type ResolvedBuildConfig = Required<Omit<BuildOptions, "sourceMap">> & {
   sourceMap?: FreshBundleOptions["sourceMap"];
 };
 
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ * The Builder class will be removed in a future version of Fresh.
+ */
 // deno-lint-ignore no-explicit-any
 export class Builder<State = any> {
   #transformer: FileTransformer;

packages/fresh/src/dev/mod.ts

@@ -1,10 +1,25 @@
-export {
-  Builder,
-  type BuildOptions,
-  type ResolvedBuildConfig,
-} from "./builder.ts";
-export {
-  type OnTransformArgs,
-  type OnTransformOptions,
-  type TransformFn,
-} from "./file_transformer.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ * The Builder API will be removed in a future version of Fresh.
+ */
+export { Builder } from "./builder.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ */
+export type { BuildOptions } from "./builder.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ */
+export type { ResolvedBuildConfig } from "./builder.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ */
+export type { OnTransformArgs } from "./file_transformer.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ */
+export type { OnTransformOptions } from "./file_transformer.ts";
+/**
+ * @deprecated Use the Vite plugin (`@fresh/plugin-vite`) instead.
+ */
+export type { TransformFn } from "./file_transformer.ts";

packages/init/src/init.ts

@@ -61,7 +61,7 @@ ${colors.rgb8("OPTIONS:", 3)}
     ${colors.rgb8("--tailwind", 2)}   Use Tailwind for styling
     ${colors.rgb8("--vscode", 2)}     Setup project for VS Code
     ${colors.rgb8("--docker", 2)}     Setup Project to use Docker
-    ${colors.rgb8("--builder", 2)}    Setup with builder instead of vite
+    ${colors.rgb8("--builder", 2)}    (Deprecated) Setup with builder instead of vite
     ${colors.rgb8("--help, -h", 2)}   Show this help message
 `;
 
@@ -141,6 +141,15 @@ export async function initProject(
 
   const useVite = !flags.builder;
 
+  if (flags.builder) {
+    console.log(
+      "\n%cWarning:%c The --builder flag is deprecated. The Builder API will be removed in a future version of Fresh. Use Vite instead (the default).",
+      "color: yellow; font-weight: bold",
+      "",
+    );
+    console.log();
+  }
+
   const useDocker = flags.docker;
   let useTailwind = flags.tailwind || false;
   if (flags.tailwind == null) {

packages/plugin-tailwindcss-v3/src/mod.ts

@@ -5,6 +5,9 @@ import cssnano from "cssnano";
 import autoprefixer from "autoprefixer";
 import * as path from "@std/path";
 
+/**
+ * @deprecated Use the Vite plugin with `@tailwindcss/vite` instead.
+ */
 export interface AutoprefixerOptions {
   /** environment for `Browserslist` */
   env?: string;
@@ -46,10 +49,17 @@ export interface AutoprefixerOptions {
   ignoreUnknownVersions?: boolean;
 }
 
+/**
+ * @deprecated Use the Vite plugin with `@tailwindcss/vite` instead.
+ */
 export interface TailwindPluginOptions {
   autoprefixer?: AutoprefixerOptions;
 }
 
+/**
+ * @deprecated Use the Vite plugin with `@tailwindcss/vite` instead.
+ * This plugin is only compatible with the legacy Builder API.
+ */
 export function tailwind(
   builder: Builder,
   options: TailwindPluginOptions = {},

packages/plugin-tailwindcss/src/mod.ts

@@ -3,9 +3,15 @@ import twPostcss from "@tailwindcss/postcss";
 import postcss from "postcss";
 import type { TailwindPluginOptions } from "./types.ts";
 
-// Re-export types for public API
+/**
+ * @deprecated Use the Vite plugin with `@tailwindcss/vite` instead.
+ */
 export type { TailwindPluginOptions } from "./types.ts";
 
+/**
+ * @deprecated Use the Vite plugin with `@tailwindcss/vite` instead.
+ * This plugin is only compatible with the legacy Builder API.
+ */
 export function tailwind(
   builder: Builder,
   options: TailwindPluginOptions = {},