インストール

既存の Next.js / Vite + React プロジェクトに @gunjo/ui を導入する手順。

前提

  • 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

⁠beta 段階の注意⁠：0.1.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 に依存しないよう、自分でインストールしてください。

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

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

npm 版 @gunjo/ui@0.1.0-beta.2（それ以前の beta も同様）を Next.js 16（Turbopack）の Server Component（layout.tsx / page.tsx など）から import { X } from "@gunjo/ui" の形（バレル import）で使うと、next build が次のエラーで失敗します：

TypeError: createContext is not a function

原因は、Turbopack がパッケージ本体（バレル）経由の解決時に内部の "use client" 境界を正しく扱えず、client 専用モジュールが Server 側で評価されるためです。next dev では発生せず、next build で顕在化します。

回避策として、"use client" を付けた再エクスポートファイルを 1 枚作り、アプリからの import はそこを経由させてください：

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

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

コンポーネント単位の subpath exports（@gunjo/ui/table など）の npm 公開と推奨経路化を予定しています。公開後はこのシムは不要になる見込みです。

トラブルシューティング

  • ⁠createContext is not a function で next build が落ちる⁠ → Server Component からのバレル import が原因。"use client" 再エクスポートシムを経由させる（上記「Server Component から使う場合」）。
  • ⁠SyntaxError: Unexpected token でビルドが落ちる⁠ → next.config.ts の transpilePackages 入れ忘れ（手順 2）。
  • ⁠Tailwind クラスが効かない⁠ → v4 の @source または v3 の content で node_modules/@gunjo/ui/src/**/* を指していない。
  • ⁠画面が真っ黒・真っ白⁠ → @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 個別の調整、フォント設定、既存アプリへの段階移行は 採用ガイド に。トークンの上書きは テーマ を参照。