インストール

パッケージのインストール

npm install @caroainc/ui-components

peerDependencies

React / React DOMは、利用プロジェクト側で対応する同一major（18または19）を選んで宣言してください。CLIはReactのversionを自動選択しません。その他の必須パッケージは以下です：

# Tailwind CSS v4が必須
npm install tailwindcss@^4 tw-animate-css@^1.4 lucide-react framer-motion date-fns date-fns-tz react-day-picker react-hook-form react-icons

tw-animate-cssはCaroa UIの非optional peerDependencyです。通常のinitは、package.jsonの指定と実際に解決したpackageのversionが、どちらも^1.4.0互換であることを確認します。

CLIでセットアップ

パッケージをインストールしたプロジェクトでは、Caroa UI独自CLIで現在の構成確認とCSSセットアップができます。

# 現在のTailwind・CSS設定を確認（変更なし）
npx caroa-ui info

# 実際には変更せず、更新対象だけ確認
npx caroa-ui init --dry-run

# 実際には変更せず、CSS差分を確認
npx caroa-ui init --diff

# 確認後にCSSを更新
npx caroa-ui init

通常のinit、--dry-run、--diffはTailwind CSSまたはtw-animate-cssが未宣言の場合に停止します。さらに、実際に解決されたTailwind CSSがv4で宣言範囲を満たすことも書き込み前に確認します。--dry-runと--diffは--depsを併用しても、ファイル書き込みと依存パッケージのインストールを行いません。

apply実行のinit --depsだけは、不足しているtw-animate-cssなどの依存を導入し、Tailwind CSSが未宣言または実体が不足・非v4の場合は依存を追加してから計画を再構築します。未宣言時はtailwindcss@^4 / tw-animate-css@^1.4を使い、対応するexact/caret/tilde宣言が既にある場合は、そのrangeを広げず同じ指定で修復します。既存のTailwind宣言がv3・v5・曖昧なrangeの場合は、自動upgradeせずnpm実行前に停止します。React / React DOMは、18または19の単純なversion指定で同一majorが宣言されている必要があります。CLIはReactのversionを自動選択せず、未宣言・非対応major・major不一致・曖昧なrangeの場合はnpm実行前に停止します。

npx caroa-ui init --deps

infoでTailwind prefix modifier: unsupportedと表示された場合、Caroa UIの配布classはunprefixedのため、@import "tailwindcss"からprefix(...)を外してからinitを実行してください。

infoは、Tailwindの宣言と解決済み実体の一致状態、およびCSSのimport順序も表示します。CSS import order: invalidの場合は、late top-level @importをstyle ruleより前のimport blockへ移し、未終端の@charset / statement-form @layerがあればセミコロンで終端してからinitを実行してください。

@sourceは、プロジェクトから実際に解決された@caroainc/ui-components/distへの相対pathを使います。npm workspaceで依存がrootのnode_modulesへhoistされている場合も、その実配置に合わせて既存directiveを更新します。

ドキュメントURLはCLIから確認できます。コマンドはブラウザを自動で開かず、URLだけを出力します。

npx caroa-ui docs
npx caroa-ui docs button

CSSのインポート

Tailwind v4では、グローバルCSSからトークン・アニメーション・配布コンポーネントをCSS-first方式で読み込みます。tailwind.config.tsは不要です：

@import 'tailwindcss';
@import 'tw-animate-css';
@import '@caroainc/ui-components/tokens';
@import '@caroainc/ui-components/animations';

/* caroa-uiコンポーネントで使用されるTailwindクラスをスキャン */
@source '../node_modules/@caroainc/ui-components/dist';

既存のJS Configを使うアプリ向けには@caroainc/ui-components/presetも引き続き提供しています。新規のTailwind v4アプリでは、上記のCSS-first方式を推奨します。