インストール

前提

• Node.js 20 以上
• React 19 以上（peer は ^19.0.0 のみ。React 18 は未サポート）
• Tailwind CSS v3 または v4
• TypeScript 推奨（本パッケージは TS ソースを直接配布しているため、後述の transpilePackages 設定が必須）
• Next.js 15 以上（推奨 16）または Vite + React

1. パッケージを追加

npm install @gunjo/ui

alpha 段階の注意：0.0.1-alpha.x はドライラン採用向け公開。1.0.0 stable 前は API が変わる可能性があります。

2. Next.js 設定（必須）

@gunjo/ui は TypeScript ソースを直接配布 しているため（main: "src/index.ts"）、採用先 Next.js でトランスパイルが必要です。next.config.ts：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: ["@gunjo/ui"],
};

export default nextConfig;

これを忘れると採用先のビルドが SyntaxError: Unexpected token で落ちます。Vite の場合は optimizeDeps.include: ["@gunjo/ui"] を vite.config.ts に追加してください。

3. Tailwind プリセットを取り込む

Tailwind v4（推奨）

app/globals.css：

@import "tailwindcss";
@config "../node_modules/@gunjo/ui/tailwind-preset.js";
@source "../node_modules/@gunjo/ui/src/**/*.{ts,tsx}";
@import "@gunjo/ui/styles";

@source で GunjoUI 内部のクラスをスキャン対象に追加します（これが無いと Tailwind がライブラリ側のクラスを knwon にできません）。

Tailwind v3

tailwind.config.ts：

import type { Config } from "tailwindcss";
import gunjoPreset from "@gunjo/ui/tailwind-preset";

const config: Config = {
  presets: [gunjoPreset],
  content: [
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./node_modules/@gunjo/ui/src/**/*.{ts,tsx}",
  ],
};

export default config;

トークン CSS は app/globals.css で（Tailwind directives の 後 に）一度 import：

@import "@gunjo/ui/styles";

4. コンポーネントを使う

app/page.tsx：

import { Button, Card, CardHeader, CardContent } from "@gunjo/ui";

export default function Page() {
  return (
    <main className="p-8">
      <Card>
        <CardHeader>
          <h2 className="text-xl font-semibold">Gunjo UI が動いている</h2>
        </CardHeader>
        <CardContent className="flex gap-2">
          <Button>Primary</Button>
          <Button variant="secondary">Secondary</Button>
        </CardContent>
      </Card>
    </main>
  );
}

npm run dev でボタンが GunjoUI のスタイルで表示されれば成功。

トラブルシューティング

• SyntaxError: Unexpected token でビルドが落ちる → next.config.ts の transpilePackages 入れ忘れ（手順 2）。
• Tailwind クラスが効かない → v4 の @source または v3 の content で node_modules/@gunjo/ui/src/**/* を指していない。
• 画面が真っ黒・真っ白 → @import "@gunjo/ui/styles" が抜けている、または @import "tailwindcss" の 前 にきている。

この先

Dark mode（next-themes）、Vite 個別の調整、フォント設定、既存アプリへの段階移行は 採用ガイド に。トークンの上書きは テーマ を参照。