کاوش در ساختار یکی از مدرن ترین و مقیاس پذیر ترین دیگهای موجود در Next.js

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

🤔 چرا ما به دیگ بخار احتیاج داریم؟

تصور کنید که برای هر پروژه از ابتدا مجبور به راه اندازی ESLINT ، زیباتر ، کتاب داستان ، تست واحد ، پوشه ها و غیره هستید. این تکرارها:

• وقت گیر هستند
• خطای انسانی را افزایش دهید
• کیفیت کد متغیر ⚖

با یک دیگ بخار:

• ساختار پروژه از ابتدا تمیز و مقیاس پذیر است
• ابزارهای لازم برای توسعه و آزمایش از ابتدا آماده هستند
• تمرکز شما به جای پیکربندی روی منطق تجارت است

🌟 ویژگی های این دیگ بخار خاص

این پروژه فقط یک دیگ بخار ساده نیست بلکه یک پایه قدرتمند و انعطاف پذیر برای توسعه رابط های کاربر با Next.js است. برخی از ویژگی های مهم آن:

• ✅ ساختار مدولار و توسعه یافته با استفاده از App Router
• 🌍 پشتیبانی چند زبانه (i18n) برای پروژه های بین المللی
• 🧪 پوشش کامل تست: هر دو تست واحد با Vitest و تست های E2E با Playwright
• 📦 تنظیمات CI/CD آماده استفاده با اقدامات GitHub
• 🎨 یکپارچه با UI مانتین برای طراحی زیبا و حرفه ای
• 📚 کتاب داستان برای توسعه و آزمایش اجزای مستقل
• 🧠 ساخته شده در CLI برای ایجاد سریع ساختارهای ویژگی جدید

برای کسب اطلاعات بیشتر در مورد این پروژه ، می توانید مقاله KIT ultimate Next.js Frontend Starter را بخوانید – تمیز ، سریع ، تایپ شده

🛠 فن آوری های کلیدی مورد استفاده

این دیگ بخار از مجموعه ای از فناوری ها و ابزارهای مدرن استفاده می کند:

✨ شروع سریع

در این بخش ، ما در چند مرحله ساده پروژه BoilerPlate Front-End را روی سیستم خود تنظیم خواهیم کرد.

note: من توصیه می کنم از مقاله استفاده کنید که سریعتر از این نباشد: راه اندازی یک پروژه Next.js با یک دیگ بخار حرفه ای برای به دست آوردن قدرت کامل این دیگ بخار

🧩 پیش نیازها را نصب کنید

برای اجرای این پروژه ، به موارد زیر نیاز دارید:

• ✅ node.js نسخه 20 یا بالاتر
• ✅ PNPM (به جای NPM یا نخ)

اگر ندارید pnpm نصب شده ، ابتدا آن را نصب کنید:

npm install -g pnpm

⚙ وابستگی ها را نصب کرده و پروژه را اجرا کنید

سپس این مراحل را دنبال کنید:

1⃣ کلون مخزن را باز کنید:

git clone https://github.com/shaadcode/Nextjs-Frontend-Boilerplate.git
cd Nextjs-Frontend-Boilerplate

2 ⃣ بسته ها را نصب کنید:

pnpm i

3⃣ ایجاد .env پرونده از .env.example:

cp .env.example .env

4⃣ اجرای پروژه:

pnpm dev

این پروژه اکنون در حال اجرا است http://localhost:3000 ✅

🗂 معرفی ساختار کلی پوشه ها و پرونده ها

در اینجا نگاهی گذرا به مهمترین پرونده ها و پوشه های موجود در این دیگ بخار مشاهده می کنیم:

💡 توجه: پرونده های پیکربندی مانند .eslint.config.mjsبا .npmrcبا commitlint.config.cjs همچنین سفارش و قوام پروژه را ارائه دهید.

🔧 پیکربندی محیط توسعه

یک پروژه خوب فقط کد خوبی نیست – محیط توسعه آن نیز باید راحت ، سازمان یافته و قابل پیش بینی باشد. در این بخش ، ما در مورد مواردی بحث خواهیم کرد که تجربه توسعه دهنده را به سطح بعدی می برند.

🔹 1. تنظیمات vscode

در .vscode/ پوشه ، پرونده هایی وجود دارد که به هماهنگی بین اعضای تیم و کاهش خطاهای زیست محیطی کمک می کند:

files پرونده های مهم:

• extensions.json

  لیستی از پسوندهای توصیه شده که VScode هنگام باز کردن یک پروژه به شما ارائه می دهد.

• launch.json

  تنظیمات اشکال زدایی برای اجرای مستقیم پروژه از محیط VScode.

• settings.json

  تنظیمات محلی برای VScode ، مانند فعال کردن ESLINT ، تنظیمات نمایش پرونده و …

🔌 پسوندهای پیشنهادی (Extensions.Json):

در extensions.json پرونده ، انتخاب کوچکی از پسوندهای توصیه شده:

💡 نصب این افزونه ها تضمین می کند که همه افراد در تیم شما تجربه ای مداوم و بدون دردسر دارند.

🔹 2. محیط های توسعه

🧪 .env وت .env.example

این پروژه از فایلهای محیطی برای تعریف مقادیر حساس یا قابل تغییر استفاده می کند.

• .env.example

  الگویی برای ایجاد یک است .env پرونده حاوی کلیدهایی مانند URL ، نشانه ها ، تنظیمات API و …

• .env

  نسخه واقعی است که توسعه دهنده باید از آن کپی کند .example و مقادیر متناسب با محیط خود را تنظیم کنید.

برای ایجاد .env پرونده:

cp .env.example .env

🧬 env.d.ts وت next-env.d.ts

در پروژه هایی با TypeScript ، داشتن متغیرهای محیط تایپ بسیار مهم است:

• env.d.ts

  file فایل دستی برای تعریف نوع متغیرها در .envبشر این پرونده به جلوگیری از خطاهای TypeScript هنگام استفاده کمک می کند process.env.MY_VARبشر

• next-env.d.ts

  file فایل تولید شده توسط Next.js برای پشتیبانی از ویژگی های TypeScript و React.

🛡 این پرونده ها از اشتباهات رایج در نام های متغیر محیط جلوگیری می کنند و تجربه تایپ ایمن تری را ارائه می دهند.

🧱 ساختار پروژه

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

🔹 1. src/app مسیر

این پروژه از آن استفاده می کند روتر برنامه در Next.js ، که در src/app/ پوشه

ساختار و طرح صفحه

• مسیرها به صورت مشخص می شوند src/app/[locale]/page.tsx، کجا [locale] پشتیبانی چند زبانه را نشان می دهد.
• در layout.tsx پرونده در هر مسیر ساختار کلی صفحه مانند ناوبری ، پاورقی یا موضوع را مشخص می کند.
• در favicon.icoبا globals.cssبا global-error.tsx، و … پرونده ها برای پیکربندی کلی پروژه هستند و مختص next.js.

🌍 پشتیبانی چند زبانه ([locale])

• [locale] آیا مسیر پویا برای زبان است (به عنوان مثال /enبا /fa)
• زبانهای جدید را می توان به راحتی اضافه کرد.
• تمام صفحات در زیر مجموعه زبان مربوطه ارائه می شوند.

files پرونده های متا

• robots.ts: کنترل دسترسی به موتور جستجو
• sitemap.ts: نسل سایت برای بهتر سئو بهتر

🔹 2 src/config/ پوشه

در config/ پوشه مکانی برای تمام تنظیمات پراکنده در طول پروژه است تا از تکثیر جلوگیری شود.

تنظیمات API

• api/axios.ts: یک نمونه اختصاصی از Axios با رهگیری ایجاد کنید
• api/queryClient.ts: پرس و جو React را برای ذخیره سازی و مدیریت درخواست ها پیکربندی کنید

تنظیمات مانتین

• mantine/: شامل تنظیمات تم ، رنگ ها ، اندازه ها و متغیرهایی است که می تواند در طول پروژه استفاده شود.

پیکربندی i18n

• i18n/messages/en.json وت fa.json: حاوی کلیدهای ترجمه است
• navigation.tsبا routing.ts: مدیریت مسیرها و ترجمه آدرس ها
• request.ts: ابزاری برای ارسال درخواست های وابسته به زبان

🧭 تعریف مسیر

• Routes/: مسیرهای اصلی پروژه با ساختار مدولار مانند home.tsبا index.ts

note: بهتر است همیشه پرونده indext.ts را داشته باشید زیرا به مقیاس پذیری پروژه کمک می کند

🔹 3. src/Providers/ مسیر

در این بخش ، همه ارائه دهنده مورد نیاز این پروژه به گونه ای قرار می گیرد که همه زمینه ها از یک نقطه قابل کنترل باشند.

• client.providers.tsx: ارائه دهندگان که فقط در مرورگر اجرا می شوند (مانند مشتری پرس و جو)
• server.providers.tsx: ارائه دهندگان سمت سرور (مانند MantineProvider)
• index.tsx: نقطه جمع آوری ارائه دهنده برای قرار دادن آسان در لایه چیدمان

🎯 این جدایی پروژه را آماده و انعطاف پذیر نگه می دارد اجزای سروربشر

🔹 4. src/utils/ مسیر

در utils/ پوشه شامل توابع یاور است که در قسمت های مختلف پروژه استفاده می شود:

• getBaseURL.ts: آدرس پایه ارسال درخواست ها را تعیین می کند (برای SSR و CSR مفید است)
• url/addQueryParams.ts: یک رشته پرس و جو به URL به صورت نوع ایمن اضافه می کند

🧩 این توابع کد را خشک کرده و خطاهای تکراری را در کنترل URL کاهش می دهند.

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

🧪 ابزارهای توسعه و آزمایش

یک پروژه مدرن بدون ابزار توسعه و آزمایش مانند ماشین بدون کمربند ایمنی است! این دیگ بخار ابزارهایی را برای توسعه آسان و آزمایش قابل اعتماد فراهم می کند تا اطمینان حاصل شود که کیفیت نرم افزار همیشه بالا است.

🔹1 کتاب داستان

کتاب داستان ابزاری برای توسعه مستقل و آزمایش اجزای سازنده است. در این دیگ بخار ، مسیر آن در واقع است ./.storybook/بشر شایان ذکر است که کتاب داستان کاملاً با مانتین یکپارچه شده است

files پرونده های کلیدی:

🎯 مزایا:

• دارای مؤلفه محور توسعه
• پیش نمایش زنده از مؤلفه ها بدون نیاز به راه اندازی کل پروژه
• در مستندات تیمی و طراحی سیستم استفاده کنید

🧑‍💻 مثال:
یک مؤلفه دکمه را می توان در کتاب داستان تهیه و آزمایش کرد بدون اینکه روی هر صفحه ای از پروژه تأثیر بگذارد.

🔹 2. آزمایش واحد و E2E

این پروژه هر دو را پوشش می دهد تست واحد وت پایان به پایان (E2E) آزمایش

🧪 ویترین – آزمایش واحد

• مسیر آزمایش: ./tests/unit/
• ابزار آزمون: دنده
• در کنار کتاب داستان از TypeScript و اجرای سریع استفاده کنید

✅ Vitest تجربه آزمایش دلپذیر را با سرعت بالا ، سازگاری با Vite/React و خروجی قابل خواندن فراهم می کند.

🧪 نمایشنامه نویس – آزمایش E2E

• مسیر آزمون: ./tests/e2e/
• ابزار آزمون: نمایشنامه نویس
• تست ها را در مرورگرهای مختلف به طور خودکار اجرا کنید

🎯 نمایشنامه نویس از تعامل واقعی کاربر مانند کلیک ، تایپ کردن ، پیمایش و بازرسی DOM پشتیبانی می کند.

📌 مهم:
با تنظیمات CI در اقدامات GitHub ، این آزمایشات می تواند باشد خودکار به طوری که هرگونه تغییر جدید بلافاصله بررسی می شود.

🤖 اتوماسیون و CI/CD

یک پروژه حرفه ای باید از ابتدا برای تحویل مداوم (CI) و انتشار خودکار (CD) آماده باشد. این دیگ بخار با کمک اقدامات GitHub ، تعهدات معمولی و ابزارهای انتشار خودکار مانند انتشار معنایی ، یک چرخه توسعه مدرن را فراهم می کند.

🔹 1. اقدامات GitHub

دو پرونده گردش کار وجود دارد که در آن تعریف شده است ./.github/workflows/:

✅ i.yml

• تست های اجرا (واحد و E2E)
• فرمت و کد را بررسی کنید

📁 مراحل معمولی در این گردش کار:

- Checkout
- Setup Node & pnpm
- Install dependencies
- Run ESLint
- Run Vitest
- Run Playwright

💡 هدف از این پرونده: اطمینان حاصل کنید که قبل از ادغام در اصلی ، هیچ چیز شکسته نشده است.

🚀 انتشار.

• پس از ادغام در آن ، نسخه خودکار را انجام دهید main
• یک نسخه جدید بسازید ، یک ChangeLog ایجاد کنید و یک برچسب GIT ایجاد کنید
• بر اساس semantic-release ابزار

با هر فشار به main که حاوی تعهدات معنی دار است (به عنوان مثال feat: یا fix:) ، یک نسخه جدید به طور خودکار ساخته و منتشر می شود.

🔹 2. تعهد و اتوماسیون را آزاد کنید

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

🧪 تعهد

• بررسی می کند که پیام متعهد مطابق با استاندارد متعهد متعارف است (به عنوان مثال feat:با fix:با chore:)
• پیکربندی در commitlint.config.cjs پرونده

✅ این تضمین می کند که نسخه ها به درستی طبقه بندی می شوند (ویژگی ، اشکال ، تغییر عمده و غیره)

📝 Release.config.mjs

• پیکربندی semantic-release ابزار
• نوع نسخه سازی را مشخص می کند (نسخه معنایی)
• به طور خودکار ایجاد می کند CHANGELOG.md با هر نسخه

changeelog.md

• یک پرونده به روز شده به روز شده
• حاوی تاریخچه مفصلی از ویژگی ها ، اشکالات و تغییرات انتشار است

📦 نتیجه نهایی؟ یک فرایند توسعه حرفه ای که شامل موارد زیر است:

• ✅ بررسی و آزمایش کد خودکار
• ✅ بدون مداخله دستی جدید را بسازید و آزاد کنید
• ✅ تغییرات ساختاری و قابل ردیابی

🛠 7. CLI داخلی برای ایجاد ویژگی

برای ساده سازی توسعه و ادغام ساختار ، این دیگ بخار دارای یک اسکریپت CLI سفارشی است که به طور خودکار ساختار یک ویژگی جدید را تولید می کند.

🔍 مسیر CLI

📁 مسیر: cli/createNewFeature/
در این مسیر ، پرونده ها و ماژول ها وجود دارند که وظیفه ایجاد پوشه و پرونده های اولیه یک ویژگی را بر عهده دارند.

⚙ نحوه استفاده

برای ایجاد یک ویژگی جدید ، به سادگی دستور زیر را در ترمینال تایپ کنید:

pnpm new-feature

سپس CLI از شما می خواهد نام این ویژگی را از شما بخواهد:

What is the name of the feature?

در این بخش باید نام پرونده خود را وارد کنید. سپس باید پرونده ها و پوشه های مورد نیاز خود را انتخاب کنید.

و به عنوان مثال ، خروجی در مسیر مشخص شده تولید می شود:

src/features/userProfile/
├── components/
├── hooks/
├── api/
├── index.ts

📁 این ساختار بسته به اجرای شما ممکن است قابل تنظیم باشد.

🎯 مزایا

task وظایف تکراری را از بین می برد
in یکپارچگی ساختار پروژه را تضمین می کند
✅ مناسب برای تیم های بزرگ
✅ با الگوهای مورد علاقه خود قابل گسترش است (به عنوان مثال اضافه کردن تست ها ، سبک ها ، کتاب داستان و غیره)

🧠 نکات حرفه ای برای توسعه با این دیگ بخار

این دیگ بخار بر اساس اصول مهندسی نرم افزار مدرن طراحی شده است. در اینجا برخی از مهمترین نکاتی که آن را متفاوت و قدرتمند می کند:

🔸 جدایی نگرانی ها

در این پروژه ، همه چیز در جای خود قرار دارد:

✅ این جداسازی باعث کاهش پیچیدگی ، افزایش خوانایی و سهولت نگهداری در تیم های بزرگ می شود.

🔸 ساختار گسترده و مقیاس پذیر

دیگ بخار به گونه ای طراحی شده است که به راحتی در پروژه های کوچک و بزرگ مورد استفاده قرار می گیرد:

• پشتیبانی از چندزبانه بودن بدون تغییر صفحات اصلی
• امکان افزودن ویژگی های جدید با CLI اختصاصی
• ساختار مدولار و گسترده در Providersبا utilsبا config

🧩 هر قسمت را می توان به طور مستقل و بدون دخالت در سایر قسمت ها توسعه داد.

🔸 پشتیبانی قوی از ابزارهای آزمایش و مستندات

• کتاب داستان برای مستندات و آزمایش UI
• دنده برای آزمایش سریع و سبک وزن
• نمایشنامه نویس برای بررسی رفتار واقعی برنامه در مرورگر
• اقدامات GitHub برای اجرای خودکار این تست ها در هر تعهد

🛡 این زیرساخت آزمایش با اعتماد به نفس کامل باعث ایجاد تغییرات می شود.

به طور خلاصه:
این دیگ بخار فقط یک پروژه استارت نیست – این یک است چارچوب توسعه قابل اعتماد برای تیم های حرفه ای ، پروژه های جدی و توسعه دهندگان که به کیفیت و مقیاس پذیری اهمیت می دهند.

🧩 نتیجه گیری

در دنیای توسعه وب مدرن ، زمان پول است. با استفاده از یک آماده ، استاندارد و مقیاس پذیر دیگ بخار به شما امکان می دهد به جای تلاش با راه اندازی اولیه و ساختار پروژه ، بر حل مشکلات واقعی و اجرای ارزش تمرکز کنید.

✅ مزایای اصلی این دیگ بخار

• ساختار پوشه کاملاً مدولار و قابل درک
• پشتیبانی چند زبانه پیش فرض (I18N)
• ساخته شده بر روی روتر برنامه بعدی Next.JS
• ابزارهای پیشرفته برای توسعه و آزمایش (کتاب داستان ، ویترین ، نمایشنامه نویس)
• CI/CD خودکار با اقدامات GitHub
• CLI ساخته شده برای ساخت سریع
• تنظیمات مناسب برای توسعه تیم در VScode

🛠 چگونه می توان این دیگ بخار را گسترش داد؟

این پروژه به گونه ای طراحی شده است که می توانید آن را به راحتی با نیازهای خود تطبیق دهید:

• الگوهای سفارشی را به CLI داخلی اضافه کنید
• تم مانتین را برای سبک بصری خاص برند خود گسترش دهید
• پشتیبانی از سایر ابزارهای آزمایش مانند Cypress را اضافه کنید

🎯 این ساختار به شما امکان می دهد پروژه ها را از MVP به برنامه های سازمانی مدیریت کنید.

🤝 دعوت به مشارکت در GitHub

مانند هر پروژه دیگر ، این دیگ بخار ممکن است کامل نباشد و ممکن است مواردی داشته باشد که هنوز برطرف نشده است. من خوشحال می شوم اگر بتوانید با باز کردن درخواست کشش ، تشکیل مسئله یا حتی پیشنهاد تغییر در اسناد ، به این پلاک کمک کنید!

link پیوند مخزن

⭐ اگر این دیگ بخار را مفید دیدید ، لطفاً پروژه را در GitHub ستاره کنید و به بازخورد و مشارکت خود در بهبود آن کمک کنید!

🎉 با استفاده از این پلاک ، گام بزرگی به سمت پیشرفت حرفه ای تر ، سریعتر و قابل حفظ برداشته اید.