نصب و راه‌اندازی
راهنمای کامل نصب و پیکربندی دیزاین سیستم پرتو در پروژه Next.js
دو روش راه‌اندازی
| روش | مناسب برای |
|---|---|
| با Claude Code | وایب‌کدرها — پلاگین همه چیز را خودکار اعمال می‌کند |
| دستی | توسعه‌دهندگان فنی — کنترل کامل روی هر فایل |
روش اول — با Claude Code (توصیه‌شده)
اگر Claude Code و پلاگین پرتو نصب دارید، نیاز به هیچ‌کدام از مراحل دستی زیر نیست:
# ۱. نصب پلاگین (یک بار، هر جای دیسک)
git clone https://github.com/dadenegarco/parto-ui.git ~/parto-ui// ۲. فعال‌سازی — .claude/settings.json در ریشه پروژه
{ "plugins": ["/Users/your-username/parto-ui/claude-plugin"] }# ۳. در Claude Code اجرا کنید
/parto:setupاین دستور پروژه را اسکن می‌کند و به‌صورت خودکار next.config.mjs، tailwind.config.ts، و layout.tsx را تنظیم می‌کند.
برای راهنمای کامل پلاگین → پلاگین Claude Code
روش دوم — نصب دستی
پیش‌نیازها
- Node.js 18 یا بالاتر
- pnpm (توصیه‌شده)
- Next.js 14 یا بالاتر
- React 18 یا بالاتر
نصب
pnpm add @parto-system-design/ui next-themesراه‌اندازی در Next.js
۱. پیکربندی next.config.mjs
پکیج باید حتماً در transpilePackages قرار بگیرد، در غیر این صورت build شکست می‌خورد:
// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
transpilePackages: ['@parto-system-design/ui'],
}
export default nextConfig۲. وارد کردن CSS
استایل‌ها در یک فایل جداگانه توزیع می‌شوند. آن‌ها را در app/layout.tsx وارد کنید:
import '@parto-system-design/ui/styles.css'۳. پیکربندی Tailwind
محتوای dist پکیج را به content در tailwind.config.ts اضافه کنید تا Tailwind کلاس‌های کتابخانه را purge نکند:
// tailwind.config.ts
import type { Config } from 'tailwindcss'
const config: Config = {
darkMode: ['class', '[data-theme*="dark"]'],
content: [
'./app/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./node_modules/@parto-system-design/ui/dist/**/*.{js,mjs}',
],
}
export default config۴. تنظیم layout
// app/layout.tsx
import type { Metadata } from 'next'
import { ThemeProvider } from 'next-themes'
import '@parto-system-design/ui/styles.css'
import './globals.css'
export const metadata: Metadata = {
title: 'اپلیکیشن من',
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="fa" dir="rtl" suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="light" themes={['light', 'dark']}>
{children}
</ThemeProvider>
</body>
</html>
)
}استفاده اولیه
پس از راه‌اندازی، می‌توانید کامپوننت‌ها را import و استفاده کنید:
import { Button, Card, CardContent, CardHeader, CardTitle } from '@parto-system-design/ui'
export default function Page() {
return (
<Card>
<CardHeader>
<CardTitle>عنوان کارت</CardTitle>
</CardHeader>
<CardContent>
<p className="text-light">محتوای کارت</p>
<Button className="mt-4">اقدام کنید</Button>
</CardContent>
</Card>
)
}اضافه کردن تغییر تم
'use client'
import { useTheme } from 'next-themes'
import { Button } from '@parto-system-design/ui'
export function ThemeSwitcher() {
const { theme, setTheme } = useTheme()
return (
<div className="flex gap-2">
<Button variant={theme === 'light' ? 'default' : 'outline'} size="small" onClick={() => setTheme('light')}>
روشن
</Button>
<Button variant={theme === 'dark' ? 'default' : 'outline'} size="small" onClick={() => setTheme('dark')}>
تاریک
</Button>
</div>
)
}نکات مهم
| نکته | توضیح |
|---|---|
transpilePackages | بدون این تنظیم Next.js پکیج را کامپایل نمی‌کند و build شکست می‌خورد |
styles.css | استایل‌ها جداگانه هستند — import را فراموش نکنید |
suppressHydrationWarning | روی <html> لازم است تا هیدراسیون تم بدون warning باشد |
dir="rtl" | برای کارکرد صحیح CSS Logical Properties الزامی است |
lang="fa" | برای screen readerها و موتورهای جستجو لازم است |
راه‌اندازی در Vite (React)
پکیج پرتو با Vite نیز کار می‌کند. transpilePackages مخصوص Next.js است و برای Vite لازم نیست.
۱. نصب
pnpm add @parto-system-design/ui next-themes۲. وارد کردن CSS
در src/main.tsx:
import '@parto-system-design/ui/styles.css'
import './index.css'۳. پیکربندی Tailwind
// tailwind.config.ts
const config: Config = {
darkMode: ['class', '[data-theme*="dark"]'],
content: ['./src/**/*.{ts,tsx}', './node_modules/@parto-system-design/ui/dist/**/*.{js,mjs}'],
}۴. تنظیم HTML و ThemeProvider
در index.html:
<html lang="fa" dir="rtl"></html>در src/main.tsx یا src/App.tsx:
import { ThemeProvider } from 'next-themes'
function App() {
return (
<ThemeProvider attribute="class" defaultTheme="light" themes={['light', 'dark']}>
{/* محتوای اپلیکیشن */}
</ThemeProvider>
)
}نکته: Hydration warning در Vite/SPA وجود ندارد — suppressHydrationWarning نیاز نیست.
مشکلات رایج و راه‌حل
کامپوننت‌ها بدون استایل نمایش داده می‌شوند
علت: CSS import فراموش شده یا مسیر اشتباه است.
// ✅ درست — در app/layout.tsx
import '@parto-system-design/ui/styles.css'
// ❌ اشتباه — import از index.js نه styles
import '@parto-system-design/ui'خطای build: SyntaxError: Cannot use import statement
علت: پکیج در transpilePackages نیست.
// next.config.mjs ✅
const nextConfig = {
transpilePackages: ['@parto-system-design/ui'],
}کلاس‌های Tailwind کار نمی‌کنند
علت: مسیر dist به content پیکربندی Tailwind اضافه نشده و Tailwind کلاس‌ها را purge کرده.
// tailwind.config.ts ✅
content: [
// ...
'./node_modules/@parto-system-design/ui/dist/**/*.{js,mjs}',
]تم پس از refresh به حالت پیش‌فرض برمی‌گردد
علت: suppressHydrationWarning روی <html> نیست یا attribute="class" در ThemeProvider جا افتاده.
// ✅ درست
<html lang="fa" dir="rtl" suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="light">layout کامپوننت‌ها معکوس است (RTL کار نمی‌کند)
علت: dir="rtl" روی <html> نیست. CSS Logical Properties به این attribute نیاز دارند.
// ✅ لازم است
<html lang="fa" dir="rtl">هشدار hydration mismatch در کنسول
علت: کامپوننت‌های تم-aware بین SSR و CSR تفاوت دارند. این طبیعی است و با suppressHydrationWarning برطرف می‌شود.
<html suppressHydrationWarning> {/* این warning را حذف می‌کند */}