راهنمای پیکربندی Nuxt 4 – بخش ۳

هدف از پیکربندی در Nuxt

Nuxt به‌صورت پیش‌فرض با تنظیمات استاندارد و قابل استفاده شروع می‌کند.
اما شما می‌توانید با فایل‌های زیر رفتار آن را تغییر دهید:

• nuxt.config.ts → برای تنظیمات اصلی، ماژول‌ها، رندر، مسیرها و سرور
• app.config.ts → برای تنظیمات ظاهری و عمومی (مثل عنوان سایت و تم)

ساختار پایه فایل nuxt.config.ts

فایل nuxt.config.ts تنظیمات اصلی برنامه را شامل می‌شود:

export default defineNuxtConfig({
  // تنظیمات شما
})

در این فایل می‌توانید:

• ماژول اضافه کنید
• حالت رندر را تغییر دهید (SSR, SSG, SPA)
• رفتار پروژه را شخصی‌سازی کنید
• پیکربندی ابزارهایی مثل Vite، PostCSS یا Nitro را بنویسید

تنظیمات مخصوص محیط‌ها (Environment Overrides)

می‌توانید برای هر محیط (مثلاً production، development یا staging) پیکربندی جدا داشته باشید:

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {},
  $env: { staging: {} },
})

اجرای Nuxt با محیط خاص:

npx nuxt build --envName staging

نکته: برای پروژه‌هایی که روی چند سرور یا محیط اجرا می‌شوند (مثل Vercel یا سرور تست)، این ویژگی بسیار مفید است.

runtimeConfig — متغیرهای محیطی و توکن‌های خصوصی

برای مقادیری که باید بعد از build قابل تغییر باشند (مثل API key یا secretها)، از runtimeConfig استفاده کنید:

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',
    public: {
      apiBase: '/api'
    }
  }
})

در .env:

NUXT_API_SECRET=my_secret_token

در کد Vue:

const config = useRuntimeConfig()

فقط مقادیر درون public در سمت کاربر (client) قابل دسترسی هستند.
هرگز اطلاعات حساس را آنجا قرار ندهید.

app.config.ts — تنظیمات ثابت و ظاهری

برای مقادیری که در زمان build مشخص‌اند (مثل رنگ‌ها، عنوان سایت یا حالت تم)، از app.config.ts استفاده کنید:

export default defineAppConfig({
  title: 'My Nuxt App',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000',
    },
  },
})

در کد Vue:

const appConfig = useAppConfig()

app.config.ts از Hot Module Replacement پشتیبانی می‌کند، یعنی اگر در زمان توسعه تغییرش دهید، بدون رفرش صفحه به‌روزرسانی می‌شود.
برای طراحی تم یا تنظیمات UI عالی است.

تفاوت بین runtimeConfig و app.config

ویژگی	runtimeConfig	app.config
تغییر با .env	✅ بله	❌ خیر
در سمت کاربر	Hydrated (در زمان اجرا)	Bundled (درون کد build)
داده‌های حساس	✅ بله	❌ خیر
تنظیمات UI	❌ خیر	✅ بله
پشتیبانی HMR	❌ خیر	✅ بله

نکته:

اگر مقدار باید بعد از build قابل تغییر باشد → runtimeConfig

اگر مقدار مربوط به ظاهر یا تم است → app.config

حذف فایل‌های پیکربندی جداگانه

در Nuxt 4 نیازی به فایل‌های جدا مثل vite.config.ts، postcss.config.js یا nitro.config.ts نیست.
همه چیز باید درون nuxt.config.ts نوشته شود.

مثلاً برای تنظیمات Vite:

export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})

۸. تنظیمات Vue و ویژگی‌های آزمایشی

برای فعال‌سازی ویژگی‌های آزمایشی در Vue مثل propsDestructure:

export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})

از نسخه Nuxt 3.9 به بعد، ویژگی reactivityTransform از هسته‌ی Vue حذف شده و در کتابخانه‌ی Vue Macros قرار گرفته است.

نکات کاربردی

• برای هر محیط (local, staging, production) فایل .env جدا بساز — Nuxt خودش آن را تشخیص می‌دهد.
• اطلاعات حساس را هرگز در runtimeConfig.public نگذار.
• از app.config.ts برای تنظیمات تم یا ظاهر استفاده کن تا بتوانی با HMR سریع تست کنی.
• با ترکیب runtimeConfig و useFetch می‌توانی endpointها را پویا بسازی:

const { public: { apiBase } } = useRuntimeConfig()
const { data } = await useFetch(`${apiBase}/posts`)

• پیکربندی ابزارها مثل Vite و Webpack را فقط در nuxt.config.ts انجام بده.
• برای تست خودکار یا CI/CD از $env.test استفاده کن.