transpilePackages and Turbopack: UI library install gotchas

Fresh Next.js apps that import the published atroui package (Host APIs) often fail until Next compiles that package with the app. The error looks like a package bug. The fix is usually one line in next.config: transpilePackages.

Pure registry UI (npx shadcn add @atroui/… only) does not need npm i atroui or transpilePackages. Use transpilePackages only when you install the package for atroui/api/* handlers.

AtroUI Host API handlers ship as TypeScript Next must compile with your app. Without transpilePackages: ["atroui"], Turbopack and webpack can refuse unknown module types or skip transforming the package.

The required config (Host API consumers)

Add AtroUI to transpilePackages alongside any other source-shipped packages you consume.

import type { NextConfig } from "next"

const nextConfig: NextConfig = {
  transpilePackages: ["atroui"],
}

export default nextConfig

Symptoms you are missing it

Unknown module type when importing from atroui.

Unexpected token / TSX parse errors inside node_modules/atroui.

Works in the monorepo docs app but breaks in a clean create-next-app consumer that uses Host APIs.

Barrel imports and heavy side paths

Prefer documented public exports from registry items you installed. Stick to paths listed in the Installation, Host APIs, and Registry guides.

CSS and peer dependencies

If a block needs next-themes or other peers, the CLI installs them. Theme failures usually mean the layout is incomplete. See ThemeProvider and dark mode.

Checklist

components.json includes the @atroui registry

npx shadcn add @atroui/… succeeded

CONTENT / DEFAULT_BRAND edited for your brand

If you use Host APIs: npm i atroui + transpilePackages: ["atroui"] - see Host APIs

Restart the Next dev server after config changes

Pure registry UI does not require the npm package - see npm → shadcn registry