Fix missing BTST styles in Tailwind CSS v4

If a BTST page loads its content but looks unstyled, check the stylesheet setup before changing its routes or data loader. A working API response does not establish that Tailwind generated the plugin's utilities or that the page received your application's theme.

This guide covers the Blog plugin and the separate Better Auth UI companion. The CSS exports were checked against @btst/stack 3.1.2 and @btst/better-auth-ui 2.0.1, with compilation checks using Tailwind CSS 4.2.1. Keep your project's compatible versions pinned while diagnosing an installation; upgrading every dependency at once makes the cause harder to identify.

Identify what is missing#

Use the browser's Elements and Network panels to separate these cases:

For one visibly broken element, inspect its class list and the matching CSS rules. An absent utility rule suggests a generation or delivery problem. A present rule whose variable is unset points to the theme. A crossed-out rule points to the cascade; adding more source scanning will not change which rule wins.

Import the Blog stylesheet#

For an application using Blog, add the public CSS export to the existing global stylesheet:

@import "tailwindcss";
@import "@btst/stack/plugins/blog/css";

This is an import fragment, not a replacement for your global CSS. Keep your current theme definitions, animation imports, dark-mode setup and application styles. If Tailwind is already imported, retain that import once and add the Blog line alongside your package imports.

The released Blog stylesheet imports its editor and content styles and registers package sources for Tailwind to scan. Importing a React component alone does not perform those CSS steps. The BTST installation reference describes the surrounding package, adapter and provider setup.

Confirm that this global stylesheet belongs to the route you are viewing. In an existing Next.js App Router application, check the root layout's global stylesheet import. In TanStack Start or React Router, check the framework's root stylesheet wiring. A CSS file sitting in the repository has no effect unless the application includes it in the delivered page.

Add the auth companion's CSS#

Better Auth UI is a separate package. For an application using both Blog and the companion, the imports are:

@import "tailwindcss";
@import "@btst/stack/plugins/blog/css";
@import "@btst/better-auth-ui/css";

An auth-only application does not need the Blog import. Use the companion's documented public export rather than inventing a @btst/stack/plugins/better-auth-ui/css path. Check that @btst/better-auth-ui is actually installed if resolution fails.

CSS does not configure an auth backend, register client plugins, or mount account routes. Follow the Better Auth UI companion documentation for those pieces. If installation fails before the CSS build begins, use the peer-dependency guide to inspect the package relationships.

Preserve the theme#

BTST's setup expects shadcn/ui with CSS variables enabled. Keep the application's token values, including its light and dark themes, and the Tailwind theme mappings that expose those tokens as utilities. In Tailwind v4, a semantic class such as bg-background needs the corresponding theme color mapping as well as a usable underlying value.

Check the computed style on a plugin surface. If the background rule refers to var(--background), inspect that variable on the element and its ancestors. If the value exists but produces an unexpected appearance, check the active theme and any overriding rule. Do not replace your established theme with a second copied palette merely to make one page look different. The shadcn theming reference explains how its semantic tokens connect to component colors.

Understand source scanning#

Tailwind's automatic detection excludes node_modules. Its @source directive can register dependency files explicitly; paths are relative to the stylesheet that declares them. BTST's documented stylesheet exports provide the relevant package integration, so start with those exports before adding broad manual scans.

For application code, use complete class names that exist in the scanned source. Constructing a class by interpolating separate pieces does not give the scanner the final utility name. See Tailwind's source detection documentation.

If a utility is still absent, inspect the installed package and the compiled output. Confirm that your build resolves the intended package version, that the CSS import reaches the processed entry point, and that the class exists in a registered source. Avoid scanning all dependencies as a first response: it makes it harder to identify the missing integration and can generate unnecessary CSS.

Check a production build#

Run your application's normal production build, serve that result, and open both the page directly and through in-app navigation. Check the delivered stylesheet requests, a plugin-specific utility, and the computed theme values. Test light and dark modes if your application supports them, including a narrow viewport and keyboard focus indicators.

For this guide, an isolated CSS fixture disabled automatic application scanning. The baseline did not generate Blog's line-clamp-3 utility. Adding the released Blog CSS export generated it; the companion and combined imports were also compiled separately. This checks stylesheet resolution and package scanning, not your application's routes, authentication, or every component's appearance.

After styling works, continue with the installation guide to verify the backend, database adapter, page routes and provider. For auth page layout changes beyond the shared theme, use the sign-in customization guide.