node_modules), so you keep full control over styling and behavior.
When shadcn/ui is a good fit
- You need reusable UI primitives across sidebar, popup, and options surfaces.
- You already use React + Tailwind in product code.
- You want source-owned components that your team can fully customize.
shadcn/ui capabilities
Template examples
Sidebar + shadcn/ui template
Use thesidebar-shadcn template as the default starting point:

Stack assumptions
- React + TypeScript
- Tailwind CSS
- PostCSS (
@tailwindcss/postcss) - Local
components/ui/*component files (shadcn-style structure)
Manual setup in an existing project
- Set up Tailwind and PostCSS (see Tailwind CSS).
- Initialize shadcn in your project and generate components.
- Keep generated UI components inside your extension source (for example,
src/components/ui/). - Import your Tailwind stylesheet in the extension entry where UI renders.
PostCSS example (Tailwind v4)
Example components.json
Usage
Use generated components from local imports:Content script notes
- Extension pages (popup/options/sidebar/new tab) are the easiest place to start with shadcn/ui.
- In a content script, a plain
import "./styles.css"evaluates to a URL for the stylesheet. It styles nothing by itself. - Extension.js places that sheet in one case only. The import must be in the entry file of a declared content script, and the script must mark a host with
data-extension-root. - The sheet then goes into the shadow root of that host. Mount your components inside that shadow root, so the Tailwind sheet reaches them.
Best practices
- Treat shadcn/ui as source-owned components, not a runtime UI package import.
- Keep Tailwind config/content paths aligned with your extension folders (
pages,scripts,src). - Start with one surface (like sidebar or popup) before adding content-script rendering complexity.
- Keep shared tokens and utility helpers in dedicated files (
lib/utils, design tokens, theme variables).
Next steps
- Set up Tailwind CSS if you have not already.
- Add linting and formatting with ESLint and Prettier.

