نحوه راه‌اندازی پروژه جدید TypeScript

مقدمه

ممکن است قبلاً هنگام استفاده از پروژه Starter یا ابزاری مثل Angular CLI با TypeScript کار کرده باشید. در این آموزش، یاد می‌گیرید چطور پروژه TypeScript را بدون کمک Starter راه‌اندازی کنید. هم‌چنین یاد می‌گیرید کامپایل در TypeScript چگونه کار می‌کند و چطور از Linter با پروژه TypeScript خودتان استفاده کنید. این راهنما شما را در نحوه راه‌اندازی پیکربندی‌های پروژه TypeScript از صفر، مقداردهی اولیه فایل‌های پروژه TypeScript و ساخت روندهای کاری جدید پروژه TypeScript راهنمایی می‌کند.

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

نکات کلیدی

• TypeScript را به‌صورت محلی نصب و پروژه‌تان را مقداردهی اولیه کنید:
  با نصب TypeScript به‌عنوان وابستگی توسعه در پروژه‌تان با npm i typescript --save-dev شروع کنید. این تضمین می‌کند هر کسی که روی پروژه کار می‌کند از همان نسخه TypeScript استفاده کند. سپس، پروژه‌تان را با npx tsc --init مقداردهی اولیه کنید؛ که فایل tsconfig.json را می‌سازد. این فایل برای پیکربندی نحوه کامپایل کدتان توسط TypeScript ضروری است و کمک می‌کند سازگاری بین محیط‌های مختلف حفظ شود.
• از tsconfig.json برای کنترل دقیق کامپایل بهره بگیرید:
  فایل tsconfig.json، قلب پیکربندی TypeScript شماست. اینجا می‌توانید گزینه‌های مهمی مانند rootDir (جایی که فایل‌های سورس‌تان زندگی می‌کنند)، outDir (جایی که JavaScript کامپایل‌شده خروجی گرفته می‌شود)، strict (برای فعال کردن بررسی تایپ سخت‌گیرانه برای کد امن‌تر) و esModuleInterop (برای بهبود سازگاری با ماژول‌های CommonJS) تعیین کنید. سفارشی کردن این تنظیمات، کامپایلر TypeScript را متناسب با ساختار و الزامات پروژه‌تان می‌کند.
• با npx tsc و حالت Watch کارآمد کامپایل کنید:
  برای تبدیل فایل‌های TypeScript خود به JavaScript، از دستور npx tsc استفاده کنید. برای تجربه توسعه نرم‌تر، می‌توانید حالت Watch را با npx tsc -w فعال کنید؛ که هر بار تغییرات را ذخیره می‌کنید، کدتان را خودکار دوباره کامپایل می‌کند. این حلقه بازخورد فوری کمک می‌کند خطاها را زود بگیرید و روند کاری‌تان را سریع کنید؛ که توسعه را بهره‌ورتر و کم‌خطاتر می‌سازد.
• Google TypeScript Style (GTS) را برای Linting و استانداردهای مقاوم یکپارچه کنید:
  با اعمال پکیج Google TypeScript Style (GTS)، فوراً راه‌اندازی Linting جامعی و مجموعه‌ای از پیش‌فرض‌های نظردار را به پروژه‌تان اضافه می‌کنید. GTS بهترین روش‌ها و سازگاری کد را الزامی می‌کند؛ و نیاز به پیکربندی دستی را کم می‌کند. این به شما اجازه تمرکز روی نوشتن کد باکیفیت را می‌دهد؛ در حالی که تضمین می‌کند پروژه‌تان از ابتدا به استانداردهای TypeScriptِ پذیرفته‌شده گسترده پایبند می‌ماند.

پیش‌نیازها

قبل از شروع کار روی این آموزش، مطمئن شوید این موارد را در جای خود دارید:

• Node.js (آخرین نسخه):
  مطمئن شوید به‌روزترین نسخه Node.js را روی کامپیوترتان نصب دارید. Node.js، Runtime جاوااسکریپتی است که TypeScript روی آن بنا می‌شود؛ و داشتن آخرین نسخه کمک می‌کند از مسائل سازگاری اجتناب و از جدیدترین قابلیت‌ها بهره ببرید. اگر راهنمایی برای نصب Node.js یا راه‌اندازی محیط توسعه محلی‌تان لازم دارید، به راهنمای جامع «نحوه نصب Node.js و ساخت محیط توسعه محلی» در پارمین کلود مراجعه کنید.
• آشنایی پایه با npm (Node Package Manager):
  باید با استفاده از npm راحت باشید؛ که هنگام نصب Node.js خودکار گنجانده می‌شود. npm برای مدیریت وابستگی‌های پروژه، نصب پکیج‌ها و اجرای اسکریپت‌ها در پروژه TypeScript شما ضروری است. اگر با npm تازه‌وارد هستید یا می‌خواهید درک‌تان را عمیق‌تر کنید، خواندن «نحوه استفاده از ماژول‌های Node.js با npm و package.json» در پارمین کلود را توصیه می‌کنیم.

برقراری این پیش‌نیازها تجربه‌ای نرم را هنگام دنبال کردن مراحل این آموزش تضمین می‌کند. اگر هر کدام را ندارید، لطفاً لحظه‌ای وقت بگذارید و منابع لینک‌شده را قبل از ادامه مرور کنید.

این مراحل روی اوبونتو 24.04 LTS (Noble)، 22.04 LTS (Jammy) و 20.04 LTS (Focal) اعتبارسنجی شده‌اند. اگر روی 18.04 یا قدیمی‌تر (الان پایان-عمر) هستید، قبل از ادامه به ریلیز پشتیبانی‌شده‌ای ارتقا دهید. برای مسیرهای گام‌به‌گام «ارتقای اوبونتوی LTS» را ببینید.

اسکریپت شروع سریع کپی-پیست

اگر می‌خواهید همه‌چیز را یک‌جا Bootstrap کنید، می‌توانید از این one-liner برای راه‌اندازی پروژه شروع TypeScript خودتان با ابزارهای رایج استفاده کنید:

npm init -y && npm i -D typescript ts-node eslint prettier @types/node && npx tsc --init

این دستور پروژه TypeScript جدیدی را مقداردهی اولیه، TypeScript و ابزارهای توسعه‌دهنده پشتیبان را نصب و فایل tsconfig.json را تولید می‌کند. راه سریعی برای ساخت پروژه TypeScript جدید بدون از دست دادن هیچ ضروری‌ای است.

گزینه‌های رایج tsconfig.json

اینجا برخی از پرکاربردترین گزینه‌هایی که می‌توانید در tsconfig.json پیکربندی کنید آمده:

گزینه	هدف
target	نسخه JavaScript برای کامپایل به آن را تعیین می‌کند (مثلاً ES6، ES2020).
module	سیستم ماژول را تعریف می‌کند (مثلاً CommonJS، ESNext).
moduleResolution	نحوه Resolve شدن ماژول‌ها را تعیین می‌کند (معمولاً روی node تنظیم می‌شود).
rootDir	پوشه ریشه فایل‌های سورس TypeScript شما (مثلاً ./src).
outDir	پوشه خروجی برای فایل‌های JavaScript کامپایل‌شده (مثلاً ./build).
strict	همه گزینه‌های بررسی تایپ سخت‌گیرانه را برای کد امن‌تر فعال می‌کند.
esModuleInterop	سازگاری با ماژول‌های CommonJS را هنگام استفاده از سینتکس ماژول ES بهبود می‌بخشد.

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

گام ۱ — شروع پروژه TypeScript

در یک نگاه — گام ۱

# one-liner برای مقداردهی اولیه پروژه TypeScript جدید
mkdir typescript-project && cd typescript-project
npm i -D typescript
npx tsc --init

توضیح تفصیلی

۱. دایرکتوری پروژه‌تان را بسازید و واردش شوید:

mkdir typescript-project
cd typescript-project

۲. TypeScript را به‌عنوان وابستگی توسعه نصب کنید:

npm i -D typescript

فلگ --save-dev تضمین می‌کند TypeScript فقط برای توسعه لازم باشد.

۳. پروژه TypeScript خودتان را مقداردهی اولیه کنید:

npx tsc --init

این، فایل tsconfig.json را با پیکربندی پیش‌فرض می‌سازد.

۴. tsconfig.json را در ویرایشگرتان باز کنید تا گزینه‌ها را بازرسی و سفارشی کنید:

nano tsconfig.json

بیشتر گزینه‌ها به‌طور پیش‌فرض کامنت شده‌اند. مثلاً:

typescript-project/tsconfig.json

{
  "compilerOptions": {
    /* برای خواندن بیشتر درباره این فایل به https://aka.ms/tsconfig.json مراجعه کنید */
    // ... (تمام گزینه‌های کامنت‌شده)
  }
}

پیکربندی را در صورت نیاز تنظیم کنید؛ مثل تنظیم "outDir": "./build" برای کنترل اینکه فایل‌های کامپایل‌شده کجا بروند.

نکته: گام ۳ بعداً بسیاری از پیکربندی‌ها را با پیش‌فرض‌های نظردار جایگزین می‌کند؛ اما این راه‌اندازی شما را سریع شروع می‌کند.

گام ۲ — کامپایل پروژه TypeScript

در یک نگاه — گام ۲

# فایل TypeScript اصلی خودتان را بسازید
echo "const world = 'world';

export function hello(who: string = world): string {
  return \`Hello \${who}!\`;
}
" > index.ts

# پروژه TypeScript را کامپایل کن
npx tsc

توضیح بیشتر

۱. کد TypeScript خودتان را در index.ts بنویسید:

typescript-project/index.ts

const world = 'world';

export function hello(who: string = world): string {
  return `Hello ${who}!`;
}

۲. کدتان را کامپایل کنید:

npx tsc

این، JavaScript کامپایل‌شده را در پوشه build تولید می‌کند (اگر outDir تنظیم شده باشد).

ساختار پروژه بعد از کامپایل:

typescript-project/
├── build/
│   ├── index.js
│   └── index.js.map
├── index.ts
└── tsconfig.json

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

typescript-project/build/index.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.hello = void 0;
const world = 'world';
function hello(who = world) {
    return `Hello ${who}!`;
}
exports.hello = hello;

کد کامپایل‌شده را با Node اجرا کنید:

node build/index.js

خروجی مورد انتظار:

(بدون خروجی—مگر اینکه تابع را Invoke کنید؛ برای نمایش زیر را اضافه کنید)

برای گرفتن خروجی، index.ts خودتان را با این به‌روزرسانی کنید:

console.log(hello());

سپس دوباره کامپایل و اجرا کنید:

npx tsc
node build/index.js

خروجی مورد انتظار:

Hello world!

حالت Watch برای کامپایل خودکار:

npx tsc -w

این، کدتان را با هر بار ذخیره دوباره کامپایل می‌کند.

گام ۳ — استفاده از Google TypeScript Style برای Lint و اصلاح کد

در یک نگاه — گام ۳

# Google TypeScript Style (GTS) را نصب کن
npm install --save-dev gts

# GTS را در پروژه‌ات مقداردهی اولیه کن
npx gts init

# کامپایل و چک خطاهای lint
npm run compile
npm run check

مثال: خطای Lint و رفع

کد بد (با خطای lint):

function sayhi(name:string){console.log('Hi, '+name)}

چک lint را اجرا کنید:

npm run check

Output
index.ts:1:10: Missing space before function parentheses.
index.ts:1:20: Missing space after colon.
index.ts:1:47: Missing semicolon.
Found 3 errors.

کد اصلاح‌شده:

function sayHi(name: string) {
  console.log('Hi, ' + name);
}

توضیح

GTS، راهنمای استایل، Linter و اصلاح‌کننده کد را در یکی فراهم می‌کند. پروژه‌تان را با پیش‌فرض‌های نظردار—including یک tsconfig.json، کانفیگ ESLint و اسکریپت‌های npm—Bootstrap می‌کند:

• npm run compile — کد TypeScript شما را کامپایل می‌کند.
• npm run check — خطاهای lint/استایل را چک می‌کند.
• npm run fix — مسائل lint را خودکار رفع می‌کند.

برای سفارشی کردن قوانین، کانفیگ ESLint را Extend کنید:

---
extends:
  - './node_modules/gts'

بهترین روش‌ها

تنظیمات کلیدی tsconfig.json

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./build",
    "strict": true,
    "esModuleInterop": true,
    "module": "nodenext",
    "moduleResolution": "node",
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true
  }
}

منطق tsconfig.json

module: “nodenext” در مقابل commonjs:

از "nodenext" برای پروژه‌های هدف‌گیرنده ماژول‌های ES در Node.js (Node 16+) استفاده کنید. از "commonjs" برای پروژه‌های کلاسیک Node.js یا سازگاری قدیمی‌تر.

moduleResolution: “node” در مقابل “bundler”:

"node" منطق Resolution مربوط به Node.js را تقلید می‌کند؛ برای سمت سرور و بیشتر پروژه‌ها بهترین است. "bundler" برای پروژه‌های فرانت‌اندی است که از ابزارهایی مثل Vite یا Webpack استفاده می‌کنند؛ که Resolution را متفاوت مدیریت می‌کنند.

skipLibCheck:

روی true تنظیم کنید تا بیلدها با رد کردن بررسی تایپ روی کتابخانه‌های موجود در node_modules سریع شوند.

noUncheckedIndexedAccess:

دسترسی امن‌تر به آرایه‌ها و Objectها را الزامی می‌کند؛ با برگرداندن possibly undefined برای دسترسی ایندکسی مگر چک شود.

بهترین روش‌های عمومی

• سورس کد را در src/ و خروجی را در build/ یا dist/ سازمان‌دهی کنید.
• برای متغیرها/توابع از camelCase و برای کلاس‌ها/تایپ‌ها از PascalCase استفاده کنید.
• همیشه "strict": true را برای بررسی تایب مقاوم فعال کنید.
• از interfaceها/typeها برای امضای واضح Object و تابع استفاده کنید.

موارد استفاده رایج

TypeScript معمولاً در این سناریوها استفاده می‌شود:

اپ‌های Node.js و Express

شروع سریع (Express):

npm i express @types/express @types/node

Express به‌همراه Typingهای TypeScript برای Express و Node را نصب می‌کند تا کامپایلر APIهای فریم‌ورک و Globalهای Node را حین توسعه بشناسد:

// index.ts
import express from 'express';
const app = express();
app.get('/', (req, res) => res.send('Hello from Express + TypeScript!'));
app.listen(3000, () => console.log('Server running on http://localhost:3000'));

این، HTTP سرور مینیمالی تعریف می‌کند که GET / را مدیریت و روی پورت ۳۰۰۰ گوش می‌دهد.

به package.json اضافه کنید:

"scripts": {
  "dev": "ts-node index.ts"
}

این اسکریپت dev، اپ را با ts-node اجرا می‌کند؛ تا بتوانید بدون قدم بیلد جداگانه Iterate کنید.

سرور را اجرا کنید:

npx ts-node index.ts
# یا
npm run dev

اگر خطای «address already in use» دیدید، app.listen(3000) را به پورت آزاد دیگری (مثلاً 3001) تغییر بدهید و دوباره اجرا کنید.

برای دیدن خروجی به http://localhost:3000 بروید. باید «Hello from Express + TypeScript!» را در مرورگرتان ببینید.

اپلیکیشن‌های React

شروع سریع (React):

npx create-react-app my-app --template typescript
# یا با Vite:
npm create vite@latest my-app -- --template react-ts

نمونه Props تایپ‌شده:

type GreetingProps = { name: string };
const Greeting: React.FC<GreetingProps> = ({ name }) => (
  <div>Hello, {name}!</div>
);

توسعه کتابخانه/پکیج

"declaration": true را در tsconfig.json تنظیم کنید تا فایل‌های .d.ts برای مصرف‌کننده‌ها تولید شوند.

عیب‌یابی خطاهای رایج

هنگام راه‌اندازی یا کار با TypeScript، مبتدیان اغلب به چند مسئله رایج برمی‌خورند. اینجا برخی خطاهایی که ممکن است با آن‌ها روبه‌رو شوید و نحوه رفع‌شان آمده:

• Cannot find name ‘require’: این وقتی رخ می‌دهد که سعی کنید در فایل TypeScriptای بدون تایپ‌های Node.js از require استفاده کنید. با نصب @types/node و اطمینان از تنظیم "moduleResolution": "node" در tsconfig.json رفعش کنید.
• Unexpected token ‘export’: این وقتی رخ می‌دهد که JavaScript کامپایل‌شده‌تان از ماژول‌های ES استفاده کند اما Node.js انتظار CommonJS داشته باشد. با تنظیم "module": "commonjs" در tsconfig.json یا اجرای Node با --experimental-modules رفعش کنید.
• نبود @types/node: اگر خطاهای تایپ مفقود برای Globalهای Node.js می‌بینید، با npm i -D @types/node نصبشان کنید.
• مسائل esModuleInterop: اگر Importها طبق انتظار کار نمی‌کنند (مثلاً با Importهای default در مقابل named)، "esModuleInterop": true را در tsconfig.json فعال کنید.
• خطاهای زمان-اجرای ts-node: اگر ts-node با خطاهای تایپ شکست می‌خورد، مطمئن شوید tsconfig.json درست پیکربندی شده، نسخه درست TypeScript را دارید و در صورت نیاز فقط برای عبور از بررسی تایپ در زمان اجرا با npx ts-node --transpile-only اجرا کنید.

سوالات متداول

چطور پروژه TypeScript را مقداردهی اولیه کنم؟

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

npm init -y
npm i -D typescript
npx tsc --init

هدف tsconfig.json چیست؟

tsconfig.json نحوه کامپایل کدتان توسط TypeScript را پیکربندی می‌کند—گزینه‌هایی مثل نسخه target جاوااسکریپت، سیستم ماژول، دایرکتوری ریشه و دایرکتوری خروجی.

آیا باید TypeScript را سراسری یا محلی نصب کنم؟

نصب محلی (npm i -D typescript) توصیه می‌شود تا همه اعضای تیم از همان نسخه استفاده کنند. اگر tsc را همه‌جا لازم دارید می‌توانید سراسری نصب کنید.

چطور کد TypeScript را بدون کامپایل هر بار اجرا کنم؟

از ts-node استفاده کنید؛ که فایل‌های .ts را مستقیم اجرا می‌کند:

npx ts-node index.ts

تفاوت tsc و ts-node چیست؟

• tsc: TypeScript را به فایل‌های JavaScript کامپایل می‌کند.
• ts-node: فایل‌های TypeScript را مستقیم اجرا می‌کند؛ بدون ساخت خروجی‌های .js جداگانه.

آیا می‌توانم از TypeScript با فریم‌ورک‌هایی مثل React یا Express استفاده کنم؟

بله. برای React، می‌توانید پروژه جدیدی با این Scaffold کنید:

npx create-react-app my-app --template typescript

برای Express، @types/express را نصب و از TypeScript برای امنیت تایپ در توسعه بک‌اند استفاده کنید.

ساخت MCP Server با TypeScript SDK

فراتر از پروژه‌های سنتی TypeScript، می‌توانید از TypeScript برای ساخت سرورهای قدرتمندی که مستقیماً با LLMها تعامل می‌کنند—با استفاده از Model Context Protocol (MCP) TypeScript SDK—هم استفاده کنید. MCP راه استانداردشده‌ای برای افشای Resourceها، Toolها و Promptهاست تا سیستم‌های AI بتوانند آن‌ها را قابل اعتماد مصرف کنند.

نمای کلی

MCP TypeScript SDK این موارد را آسان می‌کند:

• ساخت MCP Serverهایی که داده را به‌عنوان Resource افشا می‌کنند
• ثبت Toolهایی که اقدامات یا محاسبات انجام می‌دهند
• تعریف Promptهای قابل استفاده مجدد برای روندهای کاری LLM
• استفاده از Transportهایی مثل stdio یا Streamable HTTP برای ارتباط با کلاینت‌ها

این به شما اجازه ساخت سرورهای قدرت‌گرفته از TypeScript که عملکردی را امن به اپلیکیشن‌های مبتنی بر LLM فراهم می‌کنند را می‌دهد.

نصب

MCP SDK را از طریق npm نصب کنید:

npm install @modelcontextprotocol/sdk

Node.js نسخه v18 یا بالاتر لازم دارد.

مثال شروع سریع

اینجا MCP Server ساده‌ای هست که ابزار ماشین‌حساب و Resource خوش‌آمدگویی داینامیک فراهم می‌کند:

import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// ساخت MCP server
const server = new McpServer({
    name: 'demo-server',
    version: '1.0.0'
});

// ثبت ابزار جمع
server.registerTool(
    'add',
    {
        title: 'Addition Tool',
        description: 'Add two numbers',
        inputSchema: { a: z.number(), b: z.number() }
    },
    async ({ a, b }) => ({
        content: [{ type: 'text', text: String(a + b) }]
    })
);

// ثبت resource خوش‌آمدگویی داینامیک
server.registerResource(
    'greeting',
    new ResourceTemplate('greeting://{name}', { list: undefined }),
    {
        title: 'Greeting Resource',
        description: 'Dynamic greeting generator'
    },
    async (uri, { name }) => ({
        contents: [
            {
                uri: uri.href,
                text: `Hello, ${name}!`
            }
        ]
    })
);

// شروع transport از طریق stdio
const transport = new StdioServerTransport();
await server.connect(transport);

اجرای و تأیید:

npx ts-node server.ts

خروجی مورد انتظار:

MCP server started and listening for requests via stdio...

چرا MCP؟

MCP با سرورها مثل API برای LLMها رفتار می‌کند:

• Resourceها — زمینه یا داده فراهم می‌کنند (مشابه Endpointهای GET).
• Toolها — اقدامات انجام می‌دهند (مشابه Endpointهای POST).
• Promptها — قالب‌های قابل استفاده مجدد برای تعاملات ساختاریافته LLM.

این رویکرد به شما اجازه ساخت اپلیکیشن‌های قدرت‌گرفته از AI در TypeScript را می‌دهد که قابل ترکیب، قابل تست و سازگار با استانداردها هستند.

برای مستندات بیشتر، مستندات رسمی MCP و مخزن TypeScript SDK را ببینید.

نتیجه‌گیری

این راهنما نشان داد چطور پروژه TypeScript جدیدی راه‌اندازی، tsconfig.json را با بهترین روش‌های مدرن پیکربندی، کد را کامپایل و اجرا و استانداردهای کد را با Google TypeScript Style (GTS) الزامی کنید. هم‌چنین یاد گرفتید چطور پروژه‌های Node.js/Express و React را با TypeScript ساختاردهی و MCP Server بسازید.