وارد کردن پکیج

Package Imports به شما اجازه می‌دهد به‌جای استفاده از compilerOptions.paths در tsconfig.json، aliasهای خصوصی #... را مستقیماً در package.json تعریف کنید.

مثال#

در package.json، بخش imports را تعریف کنید:

Copy{
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  }
}

حالا می‌توانید کامپوننت‌ها و فایل‌های تولیدشده را با aliasهای #... وارد کنید:

Copyimport { Button } from "#components/ui/button"
import { cn } from "#lib/utils"

مسیرهای Package Imports باید با # شروع شوند.

برای استفاده از این قابلیت، از TypeScript 5 یا بالاتر استفاده کنید و در tsconfig.json این تنظیمات را فعال کنید:

Copy{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonImports": true
  }
}

پروژه‌های معمولی#

برای پروژه‌هایی که کامپوننت‌ها را در همان workspace نصب می‌کنند، می‌توانید مسیرهای Package Imports را در package.json تعریف کنید.

تنظیم package.json#

Copy{
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  }
}

اگر پروژه شما پوشه src ندارد، آن را از مسیرها حذف کنید:

Copy{
  "imports": {
    "#components/*": "./components/*.tsx",
    "#lib/*": "./lib/*.ts",
    "#hooks/*": "./hooks/*.ts"
  }
}

تنظیم TypeScript#

در tsconfig.json امکان resolve کردن Package Imports را فعال کنید:

Copy{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonImports": true
  }
}

برای این aliasها نیازی به compilerOptions.paths ندارید.

تنظیم components.json#

همان aliasهای #... را در components.json نیز استفاده کنید:

Copy{
  "aliases": {
    "components": "#components",
    "ui": "#components/ui",
    "lib": "#lib",
    "hooks": "#hooks",
    "utils": "#lib/utils"
  }
}

alias مربوط به ui از #components/ui استفاده می‌کند و توسط الگوی #components/* در package.json پوشش داده می‌شود.

همچنین utils از #lib/utils استفاده می‌کند و توسط #lib/* پوشش داده می‌شود؛ بنابراین نیازی به تعریف #utils جداگانه نیست.

Monorepo#

در پروژه‌های Monorepo، برای فایل‌های داخل هر package از Package Imports و برای فایل‌هایی که بین workspaceها به اشتراک گذاشته می‌شوند از Package Exports استفاده کنید.

workspace اپلیکیشن#

برای مثال، apps/web/package.json:

Copy{
  "name": "web",
  "private": true,
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  },
  "dependencies": {
    "@workspace/ui": "workspace:*"
  }
}

و apps/web/components.json:

Copy{
  "aliases": {
    "components": "#components",
    "ui": "@workspace/ui/components",
    "lib": "#lib",
    "hooks": "#hooks",
    "utils": "@workspace/ui/lib/utils"
  }
}

package رابط کاربری مشترک#

برای packages/ui/package.json:

Copy{
  "name": "@workspace/ui",
  "private": true,
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  },
  "exports": {
    "./globals.css": "./src/styles/globals.css",
    "./components/*": "./src/components/*.tsx",
    "./lib/*": "./src/lib/*.ts",
    "./hooks/*": "./src/hooks/*.ts"
  }
}

و packages/ui/components.json:

Copy{
  "aliases": {
    "components": "#components",
    "ui": "#components",
    "lib": "#lib",
    "hooks": "#hooks",
    "utils": "#lib/utils"
  }
}

وقتی دستور add را از apps/web اجرا می‌کنید، فایل‌های محلی با importهای #... و فایل‌های مشترک UI از طریق @workspace/ui وارد می‌شوند:

Copyimport { Button } from "@workspace/ui/components/button"
import { LoginForm } from "#components/login-form"

پسوند فایل‌ها#

الگوی مسیر در package.json#imports مشخص می‌کند importهای تولیدشده پسوند فایل داشته باشند یا نه.

اگر مسیر شامل پسوند باشد:

Copy{
  "imports": {
    "#components/*": "./src/components/*.tsx"
  }
}

import بدون پسوند تولید می‌شود:

Copyimport { Button } from "#components/ui/button"

اگر مسیر بدون پسوند باشد:

Copy{
  "imports": {
    "#components/*": "./src/components/*"
  }
}

پسوند فایل اصلی در import باقی می‌ماند:

Copyimport { Button } from "#components/ui/button.tsx"

برای بیشتر پروژه‌ها، استفاده از پسوند در الگوی target پیشنهاد می‌شود.

رفع خطا#

اگر TypeScript نمی‌تواند یک import با #... را پیدا کند، موارد زیر را بررسی کنید:

• مسیر import با # شروع شود.
• بخش imports در نزدیک‌ترین package.json تعریف شده باشد.
• مقدار moduleResolution روی bundler باشد.
• گزینه resolvePackageJsonImports فعال باشد.
• مسیر مقصد بعد از اضافه شدن کامپوننت واقعاً وجود داشته باشد.

اگر کامپوننت نصب شده اما importها همچنان با @/... ایجاد می‌شوند، بررسی کنید aliasهای components.json با مسیرهای Package Imports در package.json یکسان باشند.