transpilePackages and Turbopack: UI library install gotchas

Fresh Next.js apps often fail the first time they import a TypeScript-shipped UI library. The error looks like a package bug. The fix is usually one line in next.config: transpilePackages.

AtroUI ships source that 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

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.

Barrel imports and heavy side paths

Prefer documented public exports from registry items you installed. Stick to paths listed in the Installation 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"]

Restart the Next dev server after config changes

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