インストール

前提

• Node.js 20 以上
• React 19 以上（peer は ^19.0.0 のみ。React 18 は未サポート）
• Tailwind CSS v3 または v4
• TypeScript 推奨
• Next.js 15 以上（推奨 16）または Vite + React

1. パッケージを追加

npm install @gunjo/ui

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

アイコン（icon prop を使うならインストール）

Gunjo のコンポーネントはアイコンを ReactNode として受け取るだけで、グリフ自体は同梱しません。本ドキュメントのアイコン例はすべて @tabler/icons-react を使っているので、アイコンを渡すなら⁠直接の依存⁠として入れてください：

npm install @tabler/icons-react

npm のデフォルト hoisting では、この行が無くても import { IconX } from "@tabler/icons-react" が Gunjo UI 側のコピー経由で解決されることがあります。ただし ⁠pnpm⁠ や strict / nohoist の npm では壊れます。hoisting に依存しないよう、自分でインストールしてください。

重い部品（使うものだけ、subpath から import して依存を入れる）

重いライブラリを使う9つの部品は、@gunjo/ui の入口ではなく、部品ごとの入口（subpath）から import します。使う部品の依存だけを自分でインストールしてください。使わなければ何も入れなくて構いません（0.2.0 から）。

import { Button } from "@gunjo/ui";
import { DataTable, type ColumnDef } from "@gunjo/ui/table";

npm install @tanstack/react-table

2. ビルドの設定（不要）

@gunjo/ui は、コンパイル済みの JavaScript と型定義を dist/ に入れて配布しています。各コンポーネントの "use client" も残しています。

0.0.1-alpha.2 までは TypeScript のソースをそのまま配布していたので、next.config.ts に transpilePackages の設定が要りました。0.0.1-alpha.3 以降は消して構いません。

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

Tailwind v4（推奨）

app/globals.css：

@import "tailwindcss";
@config "../node_modules/@gunjo/ui/tailwind-preset.js";
@source "../node_modules/@gunjo/ui/dist/**/*.js";
@import "@gunjo/ui/styles";

@source が無いと、GunjoUI のコンポーネントが使うクラスの CSS が出力されません。

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/dist/**/*.js",
  ],
};

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 のスタイルで表示されれば成功。

Server Component から使う場合（Next.js App Router / RSC）

0.2.0 からは、Server Component（layout.tsx / page.tsx など）から import { TooltipProvider } from "@gunjo/ui" の形で使っても、そのまま next build が通ります。GUNJO の CI が変更のたびに、npm に出すのと同じ tarball を空の Next.js アプリに入れて、Turbopack と webpack の両方でビルドして確かめています（重い部品の依存は入れない状態）。

⁠経緯⁠：0.1.0-beta.1 と Next.js 16.2.10（Turbopack）で、Server Component からの import が next build を TypeError: createContext is not a function で落とすという報告がありました（2026-07-24・#684）。のちに同じ手順を試しましたが、報告された版でも再現しませんでした（2026-09-22・2026-10-11）。

それでも同じエラーが出たときは、Next.js の版と落ちたファイルを添えて #684 に知らせてください。その間は、"use client" を付けた再エクスポートを1枚挟むと通ります：

// components/ui.ts
"use client";
export {
  Button,
  Card,
  CardHeader,
  CardContent,
  // 使うコンポーネントを列挙
} from "@gunjo/ui";

// app/layout.tsx（Server Component のまま）
import { Button } from "@/components/ui";

トラブルシューティング

• ⁠createContext is not a function で next build が落ちる⁠ → 0.2.0 以降では CI で出ないことを確かめています。出たら #684 に知らせ、その間は "use client" の再エクスポートを挟む（上記「Server Component から使う場合」）。
• ⁠SyntaxError: Unexpected token でビルドが落ちる⁠ → 0.0.1-alpha.2 以前を入れている。最新版に上げ、transpilePackages の設定を消す（手順 2）。
• ⁠Tailwind クラスが効かない⁠ → v4 の @source または v3 の content で node_modules/@gunjo/ui/dist/**/*.js を指していない。
• ⁠画面が真っ黒・真っ白⁠ → @import "@gunjo/ui/styles" が抜けている、または @import "tailwindcss" の ⁠前⁠ にきている。
• ⁠アイコンの import が失敗する（Cannot find module '@tabler/icons-react'。pnpm だけで出ることが多い）⁠ → @tabler/icons-react を直接の依存として入れる（手順1）。Gunjo UI は内部で使っていますが、グリフを re-export していません。

この先

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