FarsiUI

Website · Docs · Components · Blocks · Demos

A Persian-first UI component library and design system for React + Tailwind.

Building a Persian product is more than flipping an English UI to RTL and pasting Farsi text. Numbers, dates, forms, typography, and interaction details need to be designed for Persian from the start. FarsiUI is built for that.

Components are added to your project with a CLI. You get the source, you own it, and you can change anything.

Features

• RTL-first: layout, spacing, and controls designed for right-to-left
• Persian-ready: typography, Persian digits, and natural Farsi UI patterns
• Jalali calendar: Shamsi date support in date components
• +500 components: ready-to-use building blocks for product UIs
• 6 design systems: switchable looks for docs and previews
• Your code: no locked runtime; copy, edit, and ship
• shadcn-compatible: same CLI / registry mental model
• Accessible: Base UI, Radix, and React Aria patterns

Quick start

npx farsiui@latest init
npx farsiui@latest add button

import { Button } from "@/components/ui/button"

export function Example() {
  return <Button>ادامه</Button>
}

Full guide: Installation

Repository structure

This is a pnpm monorepo.

Path	What it is
apps/v4	Main Next.js app: docs, component registry, blocks, demos
packages/shadcn	The farsiui CLI published on npm
packages/react	Shared React primitives used by the registry
packages/helpers	Shared utilities
templates/	Starter templates for new apps
skills/	Agent skills for Persian / RTL workflows

Most day-to-day work happens in apps/v4.

Deploy (Paasta / Docker)

Use the repo root as the build context (leave monorepo folder empty — not apps/v4).
A root Dockerfile installs with pnpm (required for workspace:*) and starts apps/v4 on port 4000.

Field	Value
Root / monorepo folder	(empty — whole repo)
Port	4000
Env	TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, NEXT_PUBLIC_APP_URL=https://farsiui.ir, NODE_OPTIONS=--max-old-space-size=6144

Vercel is unchanged (vercel.json at root). Do not set Paasta root to apps/v4 or install falls back to npm and fails on workspace:*.

Local development

Requirements: Node.js 20+, pnpm, Bun

After clone (exact steps)

Paths below assume the repo is at FarsiUI/ (root) and the app at FarsiUI/apps/v4.

0 — clone (any folder)

git clone https://github.com/MiladJoodi/FarsiUI.git
cd FarsiUI

1 — install deps → cwd: root FarsiUI/

pnpm install

Do not run a separate npm i / pnpm i only inside apps/v4 as the main install; this is a pnpm workspace and root install covers everything.

2 — install Bun (once per machine; registry:build calls bun)

Windows PowerShell (cwd does not matter):

powershell -c "irm bun.sh/install.ps1 | iex"

Then close and reopen the terminal so bun is on PATH.

Check:

bun --version

If it still says not recognized in the same session:

$env:Path = "$env:USERPROFILE\.bun\bin;" + $env:Path
bun --version

macOS / Linux:

curl -fsSL https://bun.sh/install | bash
# reopen terminal, then: bun --version

3 — generate styles + registry → cwd: root FarsiUI/

pnpm --filter=v4 registry:build

Same command from apps/v4:

cd apps/v4
pnpm registry:build

This writes gitignored files under apps/v4/styles/* (and related registry output). It can take several minutes.

Do not use this after a fresh clone:

pnpm registry:build --style all

--style all only builds public deploy styles. Local /docs also needs combos like base-rhea / aria-rhea, which only the full registry:build (no --style) generates.

4 — design-system CSS → cwd: root or apps/v4

# from root:
pnpm --filter=v4 ds:css

# or from apps/v4:
cd apps/v4
pnpm ds:css

Writes apps/v4/public/ds/*.

5 — start the site → cwd: root (preferred)

pnpm v4:dev

Or from apps/v4:

cd apps/v4
pnpm exec next dev --turbopack --port 4000

Open http://localhost:4000.

Checklist

#	cwd	Command
0	anywhere → then root	git clone … then cd FarsiUI
1	FarsiUI/	pnpm install
2	anywhere	install Bun + reopen terminal (bun --version)
3	FarsiUI/ or FarsiUI/apps/v4	pnpm --filter=v4 registry:build or pnpm registry:build
4	FarsiUI/ or FarsiUI/apps/v4	pnpm --filter=v4 ds:css or pnpm ds:css
5	FarsiUI/ or FarsiUI/apps/v4	pnpm v4:dev or pnpm exec next dev --turbopack --port 4000

If something breaks

Symptom	Fix (cwd)
Generated styles are missing…	step 3 again
'bun' is not recognized	step 2 + reopen terminal / fix PATH
/ → 404	delete apps/v4/.next, then step 5
/docs → 500 / missing @/styles/…-rhea	you used --style all; run full step 3

Other commands

Command	Description
pnpm v4:dev	Docs site (port 4000)
pnpm v4:build	Production build
pnpm registry:build	Full styles + registry rebuild
pnpm farsiui:dev	CLI package watch mode
pnpm lint	Lint monorepo

Prefer a fast local disk for apps/v4/.next. Network or slow drives make cold starts much slower.

Contributing

Bug reports, missing components, RTL issues, and PRs all help. See CONTRIBUTING.md.

If you want to contribute code, follow After clone above, then open a PR against main.

Credits

FarsiUI follows the shadcn/ui model: copyable components, CLI install, and registry-based delivery, adapted for Persian and RTL-first products.

License

MIT