آموزش و راهنما

Prettier چیست؟ آموزش کامل Prettier در JavaScript، React و TypeScript

در این آموزش Prettier را از صفر یاد می‌گیرید؛ از نصب و فایل تنظیمات تا Format on Save، Prettier Ignore، هماهنگی با ESLint و اجرای خودکار در CI. همچنین کدهای JavaScript، React و TypeScript تولیدشده با هوش مصنوعی را استاندارد می‌کنیم.

درواره

درواره

— 5 min read
Share
Prettier چیست؟ آموزش کامل Prettier در JavaScript، React و TypeScript

کدی که درست کار می‌کند، لزوماً خوانا، منظم و یکدست نیست. در یک پروژه واقعی ممکن است یک برنامه‌نویس از کوتیشن تکی استفاده کند، توسعه‌دهنده دیگری کوتیشن دوتایی را ترجیح دهد و ابزار هوش مصنوعی نیز کدی با فاصله‌گذاری و شکست خط متفاوت تولید کند. نتیجه، کدی است که از نظر ظاهری ناهماهنگ است و بررسی Pull Request را دشوار می‌کند.

Prettier یک ابزار قالب‌بندی خودکار کد یا Code Formatter است که این مشکل را حل می‌کند. این ابزار کد را دریافت می‌کند، ساختار آن را تحلیل می‌کند و سپس با یک سبک مشخص دوباره می‌نویسد. به‌این‌ترتیب اعضای تیم به‌جای بحث درباره فاصله‌ها، سمی‌کالن‌ها و نحوه شکستن خطوط، روی منطق برنامه تمرکز می‌کنند.

در این راهنما Prettier را به‌صورت عملی در پروژه‌های JavaScript، TypeScript، React و Node.js راه‌اندازی می‌کنیم، آن را به VS Code و ESLint متصل می‌کنیم و اجرای خودکار آن در Git و CI را نیز بررسی خواهیم کرد.

Prettier چیست؟

Prettier یک Code Formatter عقیده‌محور یا Opinionated است. عقیده‌محور بودن یعنی این ابزار مجموعه‌ای محدود از قواعد قالب‌بندی را انتخاب کرده و کد را طبق همان قواعد بازنویسی می‌کند.

برای مثال، کد زیر از نظر JavaScript معتبر است:

const getUser=(id)=>{return fetch("/api/users/"+id).then(response=>response.json())}

پس از اجرای Prettier، کد می‌تواند به شکل خواناتری تبدیل شود:

const getUser = (id) => {
  return fetch(`/api/users/${id}`).then((response) => response.json());
};

منطق برنامه تغییر نکرده است. فقط مواردی مانند فاصله‌گذاری، تورفتگی، کوتیشن‌ها، سمی‌کالن و شکست خطوط استاندارد شده‌اند.

Prettier از زبان‌ها و قالب‌های رایجی مانند موارد زیر پشتیبانی می‌کند:

  • JavaScript
  • TypeScript
  • JSX و TSX
  • JSON
  • HTML
  • CSS، SCSS و Less
  • Markdown
  • YAML
  • GraphQL
  • Vue
  • Angular

برای بعضی زبان‌ها یا قالب‌های دیگر نیز می‌توان از افزونه‌های Prettier استفاده کرد. فهرست قابلیت‌ها و روش استفاده از افزونه‌ها در مستندات رسمی Plugins توضیح داده شده است.

چرا باید از Prettier استفاده کنیم؟

مزیت Prettier فقط زیباتر کردن کد نیست. استفاده درست از آن روی سرعت توسعه، کیفیت همکاری و نگهداری پروژه تأثیر می‌گذارد.

یکدست شدن کدهای پروژه

وقتی تمام اعضای تیم از یک تنظیم مشترک استفاده کنند، کد تولیدشده توسط همه توسعه‌دهندگان ظاهر یکسانی خواهد داشت. دیگر مهم نیست چه کسی فایل را نوشته یا از چه ویرایشگری استفاده کرده است.

کاهش بحث‌های غیرضروری در Code Review

در نبود Formatter، بخشی از نظرات Pull Request به مواردی مانند تورفتگی، محل قرار گرفتن آکولاد یا طول خطوط مربوط می‌شود. Prettier این تصمیم‌ها را خودکار می‌کند تا بررسی‌کننده روی منطق، خطاها و معماری متمرکز شود.

خواناتر شدن کد تولیدشده با هوش مصنوعی

ابزارهای هوش مصنوعی ممکن است در پاسخ‌های مختلف از سبک‌های متفاوتی استفاده کنند. اجرای Prettier روی کد تولیدشده باعث هماهنگ شدن ظاهر آن با پروژه می‌شود.

البته قالب‌بندی صحیح به معنی درست بودن کد نیست. کد تولیدشده با هوش مصنوعی همچنان باید بررسی، آزمایش و در صورت نیاز اصلاح شود.

کاهش تغییرات اضافی در Git

اگر هر توسعه‌دهنده فایل‌ها را با سبک متفاوتی ذخیره کند، Git تغییرات ظاهری زیادی نمایش می‌دهد. یک Formatter مشترک باعث می‌شود Diffها بیشتر منعکس‌کننده تغییرات واقعی باشند.

ساده‌تر شدن ورود اعضای جدید

عضو جدید تیم لازم نیست ده‌ها قاعده ظاهری را حفظ کند. کافی است وابستگی‌های پروژه را نصب کند و Prettier را اجرا کند.

تفاوت Prettier و ESLint چیست؟

Prettier و ESLint مکمل یکدیگرند، اما وظیفه یکسانی ندارند.

ابزاروظیفه اصلینمونه مسئله
Prettierقالب‌بندی و ظاهر کدفاصله‌ها، تورفتگی، کوتیشن و شکست خط
ESLintتحلیل کیفیت و الگوهای کدنویسیمتغیر استفاده‌نشده، Promise مدیریت‌نشده یا الگوی نامناسب
TypeScriptبررسی نوع‌هاارسال رشته به تابعی که عدد می‌خواهد
Test Runnerبررسی رفتار برنامهاطمینان از درست بودن خروجی تابع

فرض کنید این کد را داریم:

const total = 100;
const unusedValue = 20;

console.log(total);

Prettier می‌تواند ظاهر کد را استاندارد کند، اما معمولاً درباره استفاده نشدن unusedValue هشدار نمی‌دهد. این وظیفه ESLint است.

در یک پروژه حرفه‌ای بهتر است هر دو ابزار وجود داشته باشند:

npm run format
npm run lint
npm run test

این سه فرمان سه مسئله متفاوت را بررسی می‌کنند: ظاهر کد، کیفیت ایستا و رفتار برنامه.

نصب Prettier در پروژه

طبق راهنمای نصب رسمی Prettier، بهتر است Prettier را به‌صورت محلی و با نسخه دقیق در هر پروژه نصب کنید. این کار باعث می‌شود تمام اعضای تیم و محیط CI از نسخه یکسانی استفاده کنند.

در پوشه پروژه اجرا کنید:

npm install --save-dev --save-exact prettier

در pnpm:

pnpm add --save-dev --save-exact prettier

در Yarn:

yarn add --dev --exact prettier

پس از نصب، نسخه موجود در پروژه را بررسی کنید:

npx prettier --version

نصب محلی بهتر از نصب سراسری است؛ زیرا نسخه Prettier هر پروژه داخل package.json و فایل Lock ثبت می‌شود.

ساخت فایل تنظیمات Prettier

ساده‌ترین روش، ایجاد فایل .prettierrc در ریشه پروژه است:

{}

حتی یک فایل خالی نیز به ویرایشگرها و سایر ابزارها نشان می‌دهد که پروژه از Prettier استفاده می‌کند.

برای شخصی‌سازی محدود می‌توان از تنظیمات زیر استفاده کرد:

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

Prettier قالب‌های مختلفی را برای فایل تنظیمات می‌پذیرد؛ از جمله .prettierrc، .prettierrc.json، فایل YAML و فایل‌های prettier.config.js یا prettier.config.mjs. جزئیات آن در مستندات Configuration File آمده است.

تنظیمات مهم Prettier

printWidth

طول تقریبی مطلوب برای خطوط را تعیین می‌کند:

{
  "printWidth": 100
}

printWidth یک محدودیت سخت نیست. Prettier تلاش می‌کند خطوط را نزدیک این مقدار نگه دارد، اما ممکن است بعضی خطوط کوتاه‌تر یا بلندتر باقی بمانند.

tabWidth

تعداد فاصله‌های هر سطح تورفتگی را مشخص می‌کند:

{
  "tabWidth": 2
}

useTabs

تعیین می‌کند برای تورفتگی از Tab استفاده شود یا Space:

{
  "useTabs": false
}

semi

اضافه شدن سمی‌کالن در انتهای دستورها را کنترل می‌کند:

{
  "semi": true
}

singleQuote

برای رشته‌های JavaScript و TypeScript، کوتیشن تکی را ترجیح می‌دهد:

{
  "singleQuote": true
}

این گزینه روی JSON اثر ندارد؛ زیرا استاندارد JSON به کوتیشن دوتایی نیاز دارد.

trailingComma

ویرگول انتهایی را در ساختارهای چندخطی کنترل می‌کند:

{
  "trailingComma": "all"
}

ویرگول انتهایی می‌تواند Diffهای Git را خواناتر کند؛ زیرا هنگام افزودن عضو جدید، خط قبلی تغییر نمی‌کند.

bracketSpacing

فاصله داخل آکولاد Object را مشخص می‌کند:

{
  "bracketSpacing": true
}

خروجی:

const user = { name: "Sara", role: "developer" };

arrowParens

نحوه استفاده از پرانتز برای پارامتر توابع Arrow را تعیین می‌کند:

{
  "arrowParens": "always"
}

خروجی:

users.map((user) => user.name);

endOfLine

نوع پایان خط را مشخص می‌کند:

{
  "endOfLine": "lf"
}

این تنظیم در تیم‌هایی که اعضای آن از Windows، Linux و macOS استفاده می‌کنند، می‌تواند از تغییرات غیرضروری مربوط به Line Ending جلوگیری کند.

گزینه‌ها و مقادیر پیش‌فرض ممکن است بین نسخه‌های اصلی تغییر کنند. برای مشاهده رفتار نسخه مورد استفاده پروژه، مستندات رسمی Options را بررسی کنید.

آیا باید تمام گزینه‌های Prettier را تغییر دهیم؟

معمولاً خیر. فلسفه Prettier این است که تعداد تصمیم‌های مربوط به ظاهر کد کاهش پیدا کند. اگر تقریباً تمام گزینه‌ها را تغییر دهید، بخشی از مزیت استفاده از یک Formatter استاندارد از بین می‌رود.

برای بیشتر پروژه‌ها تنظیمی شبیه نمونه زیر کافی است:

{
  "printWidth": 100,
  "singleQuote": true,
  "semi": true,
  "trailingComma": "all"
}

حتی استفاده از تنظیمات پیش‌فرض نیز انتخاب مناسبی است. مهم‌تر از انتخاب کوتیشن تکی یا دوتایی، یکسان بودن تنظیمات میان توسعه‌دهندگان، ویرایشگر و CI است.

ساخت فایل .prettierignore

نباید تمام فایل‌های پروژه را با Prettier قالب‌بندی کرد. خروجی Build، فایل‌های تولیدشده، پوشه وابستگی‌ها و بعضی فایل‌های داده بهتر است نادیده گرفته شوند.

در ریشه پروژه فایل .prettierignore را بسازید:

node_modules
dist
build
coverage
.next
.nuxt
.vite
public/generated
*.min.js
*.min.css
package-lock.json
pnpm-lock.yaml
yarn.lock

نادیده گرفتن Lock File همیشه ضروری نیست؛ برخی تیم‌ها آن را با Prettier قالب‌بندی می‌کنند و برخی ترجیح می‌دهند ابزار مدیریت بسته مسئول آن باشد. تصمیم باید با ساختار پروژه هماهنگ باشد.

Prettier قواعد فایل .gitignore موجود در همان مسیری را که فرمان از آن اجرا شده است نیز در نظر می‌گیرد، اما داشتن .prettierignore مستقل، هدف پروژه را شفاف‌تر می‌کند.

اجرای Prettier از خط فرمان

برای قالب‌بندی تمام فایل‌های پشتیبانی‌شده پروژه:

npx prettier . --write

گزینه --write فایل‌ها را مستقیماً بازنویسی می‌کند. بهتر است پیش از اجرای آن روی یک پروژه قدیمی، وضعیت Git را بررسی کنید تا تغییرات قابل مشاهده و بازگشت باشند.

برای قالب‌بندی یک پوشه مشخص:

npx prettier src --write

برای قالب‌بندی یک فایل:

npx prettier src/App.tsx --write

برای بررسی قالب‌بندی بدون تغییر فایل‌ها:

npx prettier . --check

گزینه --check برای CI مناسب است. اگر فایل قالب‌بندی‌نشده‌ای وجود داشته باشد، فرمان با وضعیت ناموفق تمام می‌شود.

روش استفاده از فرمان‌ها و الگوهای فایل در مستندات رسمی Prettier CLI توضیح داده شده است.

افزودن اسکریپت‌های Prettier به package.json

برای ساده‌تر شدن استفاده، فرمان‌ها را در package.json تعریف کنید:

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

اکنون قالب‌بندی پروژه با این فرمان انجام می‌شود:

npm run format

برای بررسی بدون تغییر فایل‌ها:

npm run format:check

این نام‌گذاری برای اعضای تیم و CI واضح است:

  • format فایل‌ها را اصلاح می‌کند.
  • format:check فقط وضعیت را بررسی می‌کند.

نصب Prettier در VS Code

در VS Code افزونه رسمی و شناخته‌شده Prettier - Code formatter با شناسه زیر را نصب کنید:

esbenp.prettier-vscode

سپس فایل .vscode/settings.json را در پروژه ایجاد کنید:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true
}

این تنظیمات باعث می‌شوند:

  • Prettier Formatter پیش‌فرض پروژه باشد.
  • هنگام ذخیره، فایل به‌صورت خودکار قالب‌بندی شود.
  • Prettier فقط در پروژه‌هایی فعال شود که فایل تنظیمات دارند.

اگر نمی‌خواهید Format on Save برای تمام زبان‌ها فعال باشد، آن را محدود کنید:

{
  "editor.formatOnSave": false,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

طبق راهنمای Editor Integration، نصب محلی Prettier در پروژه همچنان مهم است. افزونه ویرایشگر باید نسخه محلی پروژه را اجرا کند تا خروجی توسعه‌دهندگان با CI متفاوت نشود.

اجرای دستی Format در VS Code

برای قالب‌بندی دستی فایل:

  1. Command Palette را باز کنید.
  2. فرمان Format Document With... را انتخاب کنید.
  3. گزینه Prettier - Code formatter را بزنید.
  4. در صورت نیاز آن را به‌عنوان Formatter پیش‌فرض ثبت کنید.

میان‌بر رایج Format Document در Windows و Linux:

Shift + Alt + F

در macOS:

Shift + Option + F

اگر چند Formatter نصب شده باشد، تعیین editor.defaultFormatter از اجرای ابزار اشتباه جلوگیری می‌کند.

استفاده هم‌زمان از Prettier و ESLint

برای جلوگیری از تداخل قواعد قالب‌بندی ESLint با Prettier، بسته زیر را نصب کنید:

npm install --save-dev eslint-config-prettier

اگر پروژه از Flat Config جدید ESLint استفاده می‌کند، فایل eslint.config.js می‌تواند چنین ساختاری داشته باشد:

import js from "@eslint/js";
import eslintConfigPrettier from "eslint-config-prettier";

export default [
  js.configs.recommended,
  {
    rules: {
      "no-unused-vars": "warn",
    },
  },
  eslintConfigPrettier,
];

قرار دادن eslintConfigPrettier در انتهای آرایه اهمیت دارد؛ زیرا قواعد قالب‌بندی ناسازگار با Prettier را غیرفعال می‌کند.

اسکریپت‌های پروژه:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

روش پیشنهادی این است که ESLint و Prettier جداگانه اجرا شوند:

npm run lint
npm run format:check

مستندات Prettier توضیح می‌دهد که اجرای Prettier به‌عنوان یک قانون ESLint با eslint-plugin-prettier در بسیاری از پروژه‌ها ضروری نیست و می‌تواند کندتر و پرسر‌وصدا‌تر باشد. اجرای مستقیم prettier --check . معمولاً ساده‌تر است. جزئیات در راهنمای Integrating with Linters موجود است.

نمونه عملی Prettier در یک پروژه React و TypeScript

فرض کنید کامپوننت زیر توسط یک ابزار هوش مصنوعی تولید شده است:

type Model={id:string;name:string;description?:string}

export default function ModelCard({model}:{model:Model}){
return <article className="model-card"><h2>{model.name}</h2>{model.description&&<p>{model.description}</p>}<button onClick={()=>console.log(model.id)}>انتخاب مدل</button></article>
}

پس از اجرای:

npm run format

خروجی خواناتر خواهد بود:

type Model = {
  id: string;
  name: string;
  description?: string;
};

export default function ModelCard({ model }: { model: Model }) {
  return (
    <article className="model-card">
      <h2>{model.name}</h2>

      {model.description && <p>{model.description}</p>}

      <button onClick={() => console.log(model.id)}>انتخاب مدل</button>
    </article>
  );
}

Prettier ساختار JSX، تورفتگی و شکست خطوط را اصلاح کرده است، اما چند موضوع را بررسی نمی‌کند:

  • آیا console.log باید در نسخه Production باقی بماند؟
  • آیا دکمه به ویژگی‌های دسترس‌پذیری بیشتری نیاز دارد؟
  • آیا نوع Model بهتر است در فایل جداگانه باشد؟
  • آیا رویداد کلیک باید درخواست واقعی ارسال کند؟
  • آیا تست کامپوننت نوشته شده است؟

این موارد باید با Code Review، ESLint، TypeScript و تست بررسی شوند.

نمونه قالب‌بندی کد اتصال به API هوش مصنوعی

در یک برنامه Node.js ممکن است تابعی برای ارسال درخواست به API هوش مصنوعی داشته باشیم:

export async function createCompletion(messages) {
  const response = await fetch(
    "https://api.darvareh.ir/v1/chat/completions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.DARVAREH_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: process.env.DARVAREH_MODEL_ID,
        messages,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Darvareh API request failed: ${response.status}`);
  }

  return response.json();
}

در فایل .env مقادیر واقعی قرار می‌گیرند:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID

فایل .env نباید وارد Git شود:

.env
.env.*
!.env.example

کلید API را داخل JavaScript سمت مرورگر، کد React، مخزن عمومی یا فایل نمونه واقعی قرار ندهید. درخواست باید از Backend کنترل‌شده ارسال شود.

برای ساخت حساب و دریافت دسترسی می‌توانید وارد درواره شوید. فهرست مدل‌ها و قیمت‌های به‌روز نیز در صفحه مدل‌های درواره در دسترس است.

Prettier ظاهر این کد را استاندارد می‌کند، اما امنیت کلید، مدیریت خطا، Timeout، Rate Limit و صحت پاسخ همچنان مسئولیت منطق برنامه است.

تنظیم Prettier برای Monorepo

در یک Monorepo معمولاً بهتر است یک تنظیم پایه در ریشه پروژه داشته باشید:

my-monorepo/
  apps/
    web/
    api/
  packages/
    ui/
    config/
  .prettierrc
  .prettierignore
  package.json

فایل ریشه .prettierrc:

{
  "printWidth": 100,
  "singleQuote": true,
  "semi": true,
  "trailingComma": "all"
}

اسکریپت ریشه:

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

اگر بخشی از پروژه واقعاً به تنظیم متفاوتی نیاز دارد، می‌توان از overrides استفاده کرد:

{
  "printWidth": 100,
  "singleQuote": true,
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "preserve"
      }
    },
    {
      "files": "*.json",
      "options": {
        "tabWidth": 2
      }
    }
  ]
}

تنظیمات محلی متعدد را فقط در صورت نیاز واقعی اضافه کنید؛ زیرا وجود چند فایل تنظیمات می‌تواند پیدا کردن منبع رفتار Prettier را دشوار کند.

قالب‌بندی Markdown، JSON، YAML و CSS

Prettier فقط برای JavaScript نیست. می‌توانید فایل‌های مستندات و تنظیمات را نیز با همان فرمان قالب‌بندی کنید:

npx prettier README.md package.json src/styles.css config.yml --write

این ویژگی در پروژه‌هایی که مستندات API، GitHub Actions، فایل‌های JSON و کد Frontend را کنار هم نگهداری می‌کنند بسیار مفید است.

برای بررسی نوع Parser انتخاب‌شده:

npx prettier src/App.tsx --file-info

همچنین می‌توان خروجی قالب‌بندی را بدون بازنویسی فایل مشاهده کرد:

npx prettier src/App.tsx

نادیده گرفتن بخشی از کد

گاهی نمی‌خواهیم Prettier یک ساختار خاص را تغییر دهد. در JavaScript و TypeScript می‌توان از کامنت زیر استفاده کرد:

// prettier-ignore
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1],
];

برای JSX:

<div>
  {/* prettier-ignore */}
  <span     data-id="fixed-layout">متن</span>
</div>

استفاده زیاد از prettier-ignore توصیه نمی‌شود. اگر تعداد این موارد زیاد شده است، احتمالاً کد یا تنظیمات پروژه نیاز به بازنگری دارند.

اجرای Prettier قبل از Commit

برای پروژه‌های تیمی می‌توان فقط فایل‌های Stage‌شده را پیش از Commit قالب‌بندی کرد. ترکیب lint-staged و husky برای این کار رایج است.

نصب بسته‌ها:

npm install --save-dev husky lint-staged

راه‌اندازی Husky:

npx husky init

در فایل package.json:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,css,scss,md,yml,yaml}": "prettier --write"
  }
}

محتوای .husky/pre-commit:

npx lint-staged

اکنون فقط فایل‌هایی که وارد Stage شده‌اند قالب‌بندی می‌شوند. این روش معمولاً از اجرای Prettier روی کل مخزن در هر Commit سریع‌تر است.

Hook محلی نباید تنها لایه کنترل باشد؛ چون امکان غیرفعال کردن یا اجرا نشدن آن وجود دارد. بررسی نهایی را در CI نیز نگه دارید.

اجرای Prettier در GitHub Actions

یک Workflow ساده برای بررسی قالب‌بندی:

name: Code Quality

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Check formatting
        run: npm run format:check

      - name: Run ESLint
        run: npm run lint

      - name: Run tests
        run: npm test

در این Workflow، CI فایل‌ها را خودکار تغییر نمی‌دهد. فقط در صورت قالب‌بندی نبودن کد، Job شکست می‌خورد و توسعه‌دهنده باید این فرمان را اجرا کند:

npm run format

این رفتار معمولاً برای Pull Request شفاف‌تر از Commit خودکار تغییرات توسط CI است.

اضافه کردن Prettier به یک پروژه قدیمی

اجرای Prettier روی یک پروژه قدیمی می‌تواند هزاران خط را تغییر دهد. اگر این تغییرات همراه با توسعه یک قابلیت جدید باشند، Code Review بسیار سخت خواهد شد.

فرایند مناسب‌تر:

  1. وضعیت پروژه و تست‌ها را بررسی کنید.
  2. Prettier و فایل تنظیمات را اضافه کنید.
  3. پوشه‌ها و فایل‌های تولیدشده را در .prettierignore قرار دهید.
  4. فقط قالب‌بندی را در یک Commit یا Pull Request مستقل اجرا کنید.
  5. از تغییر منطق برنامه در همان Commit خودداری کنید.
  6. پس از ادغام، Format Check را به CI اضافه کنید.
  7. در صورت نیاز از Git Blame Ignore استفاده کنید.

برای جلوگیری از تأثیر Commit قالب‌بندی روی git blame، شناسه Commit را داخل فایل .git-blame-ignore-revs قرار دهید:

a1b2c3d4e5f6

سپس اعضای تیم می‌توانند Git را تنظیم کنند:

git config blame.ignoreRevsFile .git-blame-ignore-revs

استفاده از Prettier برای کد تولیدشده با هوش مصنوعی

یک گردش کار مناسب برای کد تولیدشده توسط هوش مصنوعی می‌تواند چنین باشد:

  1. مسئله و محدودیت‌ها را در پرامپت مشخص کنید.
  2. کد پیشنهادی را در یک Branch جداگانه قرار دهید.
  3. Prettier را برای استاندارد کردن ظاهر کد اجرا کنید.
  4. ESLint و TypeScript را اجرا کنید.
  5. تست‌های موجود را اجرا کنید.
  6. برای رفتار جدید تست بنویسید.
  7. Diff نهایی را به‌صورت انسانی بررسی کنید.
  8. سپس Pull Request بسازید.

فرمان نمونه:

npm run format
npm run lint
npm run typecheck
npm test

Prettier نباید به‌عنوان ابزار اعتبارسنجی کد هوش مصنوعی در نظر گرفته شود. کدی که قالب‌بندی شده است ممکن است همچنان خطای منطقی، امنیتی یا عملکردی داشته باشد.

خطاهای رایج Prettier و روش رفع آن‌ها

Prettier هنگام ذخیره اجرا نمی‌شود

ابتدا بررسی کنید افزونه VS Code فعال است و Formatter پیش‌فرض به‌درستی تعیین شده است:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}

سپس خروجی افزونه را از پنل Output مشاهده کنید. اگر prettier.requireConfig فعال است، وجود .prettierrc را نیز بررسی کنید.

فایل توسط Prettier نادیده گرفته می‌شود

فرمان زیر نشان می‌دهد آیا فایل با قواعد Ignore مطابقت دارد:

npx prettier src/App.tsx --check

فایل‌های .prettierignore و .gitignore را بررسی کنید. ممکن است یک الگوی عمومی، فایل مورد نظر را کنار گذاشته باشد.

خروجی VS Code با خط فرمان متفاوت است

این مشکل معمولاً از تفاوت نسخه‌ها یا تنظیمات ناشی می‌شود. مطمئن شوید:

  • Prettier داخل پروژه نصب شده است.
  • افزونه VS Code نسخه محلی پروژه را اجرا می‌کند.
  • فایل تنظیمات داخل Git قرار گرفته است.
  • چند Formatter هم‌زمان روی فایل اجرا نمی‌شوند.
  • فرمان از ریشه صحیح پروژه اجرا می‌شود.

Prettier خطای Syntax می‌دهد

Prettier باید بتواند کد را Parse کند. اگر فایل دارای خطای نحوی باشد، معمولاً قالب‌بندی انجام نمی‌شود.

برای مثال:

const user = {
  name: "Sara",
  role: "developer",

آکولاد بسته نشده است. ابتدا خطای Syntax را اصلاح کنید و سپس Prettier را اجرا کنید.

Prettier و ESLint دائماً تغییرات یکدیگر را برمی‌گردانند

این وضعیت نشانه تداخل قواعد قالب‌بندی است. eslint-config-prettier را نصب و در انتهای تنظیمات ESLint قرار دهید. همچنین بهتر است وظیفه قالب‌بندی را به Prettier و وظیفه تحلیل کیفیت را به ESLint بسپارید.

تمام فایل بعد از ذخیره تغییر کرده است

دلایل رایج عبارت‌اند از:

  • تفاوت Line Ending میان سیستم‌ها
  • استفاده از نسخه متفاوت Prettier
  • تغییر فایل تنظیمات
  • فعال بودن Formatter دیگر
  • نبودن تنظیمات مشترک در مخزن

برای کاهش مشکل Line Ending می‌توان در .prettierrc از این تنظیم استفاده کرد:

{
  "endOfLine": "lf"
}

Prettier یک زبان یا فایل خاص را پشتیبانی نمی‌کند

ابتدا پسوند فایل و پشتیبانی داخلی Prettier را بررسی کنید. ممکن است برای آن زبان به Plugin نیاز باشد. افزونه را فقط از منبع معتبر انتخاب و نسخه آن را در وابستگی‌های پروژه ثبت کنید.

ساختار پیشنهادی نهایی پروژه

یک پروژه React یا Node.js می‌تواند چنین فایل‌هایی داشته باشد:

project/
  src/
  tests/
  .vscode/
    settings.json
  .husky/
    pre-commit
  .prettierignore
  .prettierrc
  eslint.config.js
  package.json
  package-lock.json

نمونه .prettierrc:

{
  "printWidth": 100,
  "tabWidth": 2,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "endOfLine": "lf"
}

نمونه .prettierignore:

node_modules
dist
build
coverage
.next
public/generated
*.min.js
*.min.css

نمونه .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true
}

نمونه اسکریپت‌های package.json:

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

چک‌لیست راه‌اندازی Prettier

پیش از نهایی کردن تنظیمات، این موارد را بررسی کنید:

  • Prettier به‌صورت محلی و با نسخه دقیق نصب شده است.
  • فایل تنظیمات Prettier داخل Git قرار دارد.
  • فایل .prettierignore پوشه‌های Build و فایل‌های تولیدشده را پوشش می‌دهد.
  • اسکریپت‌های format و format:check تعریف شده‌اند.
  • VS Code از نسخه محلی Prettier استفاده می‌کند.
  • Format on Save برای اعضای تیم قابل استفاده است.
  • تداخل ESLint با eslint-config-prettier برطرف شده است.
  • بررسی قالب‌بندی در CI اجرا می‌شود.
  • کد تولیدشده با هوش مصنوعی علاوه بر قالب‌بندی، تست و بازبینی می‌شود.
  • کلیدهای API و فایل‌های محیطی وارد مخزن نمی‌شوند.

پرسش‌های متداول

آیا Prettier رایگان است؟

بله، Prettier یک پروژه متن‌باز است و می‌توان از آن در پروژه‌های شخصی و تجاری مطابق مجوز پروژه استفاده کرد.

آیا Prettier جایگزین ESLint است؟

خیر. Prettier ظاهر کد را استاندارد می‌کند، درحالی‌که ESLint الگوهای کدنویسی و مشکلات احتمالی را تحلیل می‌کند. استفاده هم‌زمان از هر دو ابزار رایج است.

آیا Prettier خطاهای برنامه را پیدا می‌کند؟

Prettier ممکن است هنگام Parse کردن، بعضی خطاهای نحوی را آشکار کند؛ اما ابزار تست، تحلیل نوع یا بررسی منطق برنامه نیست.

آیا نصب افزونه VS Code کافی است؟

برای یک آزمایش شخصی شاید کافی به نظر برسد، اما در پروژه تیمی باید Prettier را داخل خود پروژه نیز نصب کنید. در غیر این صورت نسخه ویرایشگر، اعضای تیم و CI ممکن است متفاوت باشد.

آیا باید Prettier را روی هر Save اجرا کنیم؟

برای بیشتر پروژه‌های JavaScript، React و TypeScript این روش تجربه مناسبی ایجاد می‌کند. بااین‌حال در فایل‌های بسیار بزرگ یا پروژه‌های خاص می‌توان قالب‌بندی را دستی یا فقط روی فایل‌های Stage‌شده اجرا کرد.

آیا Prettier ترتیب Importها را تغییر می‌دهد؟

Prettier اصلی معمولاً مسئول مرتب‌سازی معنایی Importها نیست. برای این کار می‌توان از ESLint یا Pluginهای مخصوص استفاده کرد، اما باید اثر آن‌ها بر کد و سازگاری نسخه‌ها را جداگانه بررسی کرد.

آیا Prettier کد را کوتاه یا بهینه می‌کند؟

خیر. Prettier ابزار Minifier یا بهینه‌ساز عملکرد نیست. هدف آن تولید کدی خوانا و یکدست است.

آیا می‌توان Prettier را فقط برای بخشی از پروژه فعال کرد؟

بله. می‌توانید مسیر مشخصی را به CLI بدهید، فایل‌ها را در .prettierignore قرار دهید یا از overrides برای الگوهای خاص استفاده کنید.

بهترین تنظیمات Prettier چیست؟

یک تنظیم واحد برای تمام پروژه‌ها وجود ندارد. در بیشتر موارد، تنظیمات پیش‌فرض یا چند گزینه محدود مانند printWidth، singleQuote و trailingComma کافی هستند. مهم‌ترین اصل، ثبت تنظیمات مشترک در مخزن است.

جمع‌بندی

Prettier یکی از ساده‌ترین ابزارهایی است که می‌تواند کیفیت تجربه توسعه در پروژه‌های JavaScript، TypeScript، React و Node.js را به‌طور ملموس بهتر کند. این ابزار بحث‌های مربوط به ظاهر کد را کاهش می‌دهد، Code Review را خواناتر می‌کند و کد نوشته‌شده توسط انسان یا تولیدشده با هوش مصنوعی را با یک سبک مشترک هماهنگ می‌سازد.

برای یک راه‌اندازی قابل اتکا، Prettier را به‌صورت محلی و با نسخه دقیق نصب کنید، فایل‌های .prettierrc و .prettierignore را داخل مخزن قرار دهید، Format on Save را در ویرایشگر فعال کنید و prettier --check . را در CI اجرا کنید. در کنار آن از ESLint، TypeScript، تست و بازبینی انسانی نیز استفاده کنید؛ زیرا قالب‌بندی منظم تنها یکی از اجزای کیفیت نرم‌افزار است.

منابع تکمیلی

مقالات مرتبط

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.

Read more

اتوماسیون هوش مصنوعی چیست؟ کاربردها و آموزش ساخت AI Automation

اتوماسیون هوش مصنوعی چیست؟ کاربردها و آموزش ساخت AI Automation

اتوماسیون هوش مصنوعی با ترکیب گردش‌کارهای خودکار و مدل‌های هوش مصنوعی، پردازش متن، دسته‌بندی، استخراج اطلاعات و تصمیم‌های پیشنهادی را خودکار می‌کند. در این راهنما، معماری و ساخت نمونه عملی آن با API درواره را می‌آموزید.
Agentic Commerce چیست؟ آینده خرید با ایجنت هوش مصنوعی

Agentic Commerce چیست؟ آینده خرید با ایجنت هوش مصنوعی

Agentic Commerce شیوه‌ای جدید برای خرید اینترنتی است که در آن ایجنت هوش مصنوعی می‌تواند نیاز کاربر را بفهمد، محصولات را جست‌وجو و مقایسه کند و فرایند خرید را پیش ببرد. در این راهنما با معماری، UCP، ACP و پیاده‌سازی آن با API درواره آشنا می‌شوید.