fix: update Tailwind CSS integration and add production configuration details

Author: benpsnyder

apps/docs-app/docs/integrations/angular-material/index.md

@@ -164,7 +164,9 @@ export default defineConfig({
 @import 'tailwindcss';
 ```
 
-> **Note:** Analog's default Tailwind v4 setup uses `@tailwindcss/vite`. You do not need a `.postcssrc.json` file or a generated `tailwind.config.*` file for the standard Vite-based setup.
+> **Note:** Analog's default Tailwind v4 setup uses `@tailwindcss/vite` for development. You do not need a generated `tailwind.config.*` file for the standard Vite-based setup.
+>
+> **For production builds** that use `@apply` in component stylesheets (`.component.css`), you also need `@tailwindcss/postcss` configured in a `postcss.config.mjs`. See the [Tailwind CSS integration guide](/docs/integrations/tailwind) for full details.
 >
 > The scaffolded Tailwind v4 flow also expects a plain CSS entry file such as `src/styles.css`. If your app currently uses Sass or Less for the global entry point, keep your existing setup or migrate that entry file to CSS before adopting the default Tailwind v4 flow.
 

apps/docs-app/docs/integrations/tailwind/index.md

@@ -47,7 +47,9 @@ pnpm create analog
 
 ### Tailwind v4
 
-`create-analog` scaffolds Tailwind v4 with the Vite plugin by default for the current Analog templates. Generated projects use `@tailwindcss/vite`, add `@import 'tailwindcss';` to `src/styles.css`, and do not create a `.postcssrc.json` file or a `tailwind.config.*` file for the standard setup.
+`create-analog` scaffolds Tailwind v4 with the Vite plugin by default for the current Analog templates. Generated projects use `@tailwindcss/vite`, add `@import 'tailwindcss';` to `src/styles.css`, and do not create a `tailwind.config.*` file for the standard setup.
+
+**For production builds** that use `@apply` in component stylesheets (`.component.css`), you should also install `@tailwindcss/postcss` and create a `postcss.config.mjs`. Without it, `@apply` directives in component styles will not be resolved during `vite build`. See the [Tailwind CSS integration guide](/docs/integrations/tailwind) for full configuration details.
 
 If you do not want Tailwind in the generated app, pass `--skipTailwind true`. The default Tailwind v4 flow expects a plain CSS entry file for global styles.
 

apps/docs-app/docs/packages/create-analog/overview.md

@@ -88,6 +88,12 @@ export interface Options {
    */
   liveReload?: boolean;
 
+  /**
+   * Enable verbose debug logging for Tailwind CSS integration, HMR, and
+   * component style processing.  Logs are prefixed with `[analog:debug]`.
+   */
+  debugTailwindCss?: boolean;
+
   /**
    * Additional page paths to include
    */

packages/platform/src/lib/options.ts

@@ -79,6 +79,7 @@ export function platformPlugin(opts: Options = {}): Plugin[] {
             liveReload: platformOptions.liveReload,
             inlineStylesExtension: platformOptions.inlineStylesExtension,
             fileReplacements: platformOptions.fileReplacements,
+            debugTailwindCss: platformOptions.debugTailwindCss,
             ...(viteOptions ?? {}),
             experimental: {
               ...(viteOptions?.experimental ?? {}),

packages/platform/src/lib/platform-plugin.ts

@@ -89,3 +89,9 @@ Create a `tsconfig.app.json` in the root of the project.
   "include": ["src/**/*.ts"]
 }
 ```
+
+## Tailwind CSS v4
+
+The plugin provides first-class Tailwind CSS v4 support for Angular component styles, including `@apply` in `.component.css` files, DaisyUI, and custom prefixes.
+
+See the [Tailwind CSS integration guide](/docs/integrations/tailwind) for full setup instructions covering CSR, SSR, SSG, library builds, Vitest, DaisyUI, and production configuration.

packages/vite-plugin-angular/README.md

@@ -86,12 +86,36 @@ export function augmentHostWithResources(
       console.error(`${e}`);
     }
 
-    return { content: stylesheetResult?.code || '' };
+    // Return null when the transform fails entirely, allowing Angular to
+    // surface the error rather than silently replacing the stylesheet with
+    // empty content.  An empty string would cause Angular to proceed as if
+    // the component had no styles — hiding preprocessing errors.
+    if (stylesheetResult?.code == null) {
+      return null;
+    }
+
+    return { content: stylesheetResult.code };
   };
 
+  /**
+   * Maps a resource name (template or stylesheet URL from a component
+   * decorator) to a file path on disk.
+   *
+   * For stylesheets when externalComponentStyles is active, creates a
+   * hash-based virtual ID and stores the mapping so that resolveId/load
+   * can serve these through Vite's pipeline.
+   *
+   * @param resourceName - The URL from the component decorator (e.g. './foo.component.css')
+   * @param containingFile - Absolute path to the .ts file that references the resource
+   * @param fallbackResolve - Optional callback from Angular's resource loader that
+   *   uses TypeScript's module resolution as a fallback. Accepted for API
+   *   compatibility but intentionally not called for stylesheets (Analog's
+   *   hash-based approach is authoritative).
+   */
   resourceHost.resourceNameToFileName = function (
-    resourceName,
-    containingFile,
+    resourceName: string,
+    containingFile: string,
+    fallbackResolve?: (url: string, fromFile: string) => string | null,
   ) {
     const resolvedPath = path.join(path.dirname(containingFile), resourceName);