Konfiguráció: nuxt.config, runtimeConfig, TypeScript

12.1A négy szint

12.2runtimeConfig a gyakorlatban

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // ── csak a szerver látja ──────────────────────────────
    sessionPassword: '',          // NUXT_SESSION_PASSWORD
    stripeSecretKey: '',          // NUXT_STRIPE_SECRET_KEY
    resendApiKey:    '',          // NUXT_RESEND_API_KEY

    upstream: {
      baseUrl: '',               // NUXT_UPSTREAM_BASE_URL
      token:   '',               // NUXT_UPSTREAM_TOKEN
    },

    // ── a kliens IS látja ─────────────────────────────────
    public: {
      appName:        'Scoope',    // NUXT_PUBLIC_APP_NAME
      siteUrl:        '',          // NUXT_PUBLIC_SITE_URL
      stripePublicKey:'',          // NUXT_PUBLIC_STRIPE_PUBLIC_KEY  ← a pk_ kezdetű, az OK
      sentryDsn:      '',          // NUXT_PUBLIC_SENTRY_DSN
    },
  },
})

Az üres string nem véletlen: a kulcsnak léteznie kell a konfigban, hogy az env-változó felül tudja írni. Ha nincs ott, a NUXT_… változó nem csinál semmit — ez a leggyakoribb „miért üres a config?” ok.

Az elnevezési szabály

runtimeConfig.stripeSecretKey        →  NUXT_STRIPE_SECRET_KEY
runtimeConfig.upstream.baseUrl       →  NUXT_UPSTREAM_BASE_URL
runtimeConfig.public.siteUrl         →  NUXT_PUBLIC_SITE_URL

Prefix mindig NUXT_, a beágyazott szintek aláhúzással, a camelCase pedig nagybetűs, aláhúzásos alakra bomlik. Az értékek automatikusan típusra konvertálódnak — ha a "3000"-et stringként akarod, idézőjelezd a .env-ben.

Olvasás — és a Workers-es csavar

// szerveroldalon: MINDIG add át az event-et
export default defineEventHandler(async (event) => {
  const cfg = useRuntimeConfig(event)      // ← az event nem opcionális szeszély
  const key = cfg.stripeSecretKey
})

// kliensoldalon: csak a public érhető el
const { public: pub } = useRuntimeConfig()
console.log(pub.siteUrl)

runtimeConfig vagy app.config.ts?

12.3A szivárgás anatómiája — és hogyan ellenőrzöd

Négy úton kerülhet titok a kliensbe, és mind a négy csendes:

A tíz másodperces ellenőrzés

# build után nézd meg, hogy a titkaid nincsenek-e a kliens-bundle-ben
npm run build
grep -ril "sk_live\|SESSION_PASSWORD\|BEGIN PRIVATE KEY" .output/public/ || echo "tiszta"

# és konkrét értékre, ha van sejtésed:
grep -ro "sk_test_[A-Za-z0-9]*" .output/public/ | head

12.4Cloudflare-oldal: vars, secret, binding

// wrangler.jsonc
{
  "name": "app",
  "main": ".output/server/index.mjs",
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["nodejs_compat"],

  "assets": { "directory": ".output/public", "binding": "ASSETS" },

  // ③ NEM titok — látszik a repóban és a dashboardon
  "vars": {
    "NUXT_PUBLIC_SITE_URL": "https://app.pelda.hu",
    "NUXT_PUBLIC_APP_NAME": "Scoope"
  },

  // + bindingok: nem érték, hanem képesség
  "hyperdrive":    [{ "binding": "APP_DB", "id": "…" }],
  "r2_buckets":    [{ "binding": "BUCKET", "bucket_name": "app-files" }],
  "kv_namespaces": [{ "binding": "CACHE", "id": "…" }]
}

# ④ a titkok NEM a configba mennek
npx wrangler secret put NUXT_SESSION_PASSWORD
npx wrangler secret put NUXT_STRIPE_SECRET_KEY
npx wrangler secret list

A lánc: honnan hova jut egy érték

fejlesztés:   .env fájl          →  process.env  →  runtimeConfig  →  useRuntimeConfig()
éles:         wrangler secret    →  Worker env   →  runtimeConfig  →  useRuntimeConfig(event)
              wrangler vars      →  Worker env   →  runtimeConfig  →  useRuntimeConfig(event)

Vagyis a kódod egyetlen helyről olvas — useRuntimeConfig(event) —, és nem tudja, hogy az érték .env-ből, vars-ból vagy secretből jött. Ez a jó: a titkok kezelése üzemeltetési kérdés marad, nem szivárog be az alkalmazáslogikába.

12.5Környezetenkénti felülírás

Nuxt-oldalon a nuxt.config.ts támogat környezet-specifikus blokkokat, amiket a c12 old fel:

export default defineNuxtConfig({
  // közös alap
  routeRules: { '/api/**': { headers: { 'cache-control': 'no-store' } } },

  $development: {
    devtools: { enabled: true },
  },

  $production: {
    routeRules: {
      '/':        { prerender: true },
      '/blog/**': { prerender: true },
    },
  },

  // saját, névvel hivatkozott környezet
  $env: {
    staging: {
      runtimeConfig: { public: { siteUrl: 'https://staging.pelda.hu' } },
    },
  },
})

nuxt build --envName staging

12.6A nuxt.config.ts — mit hova

Egy valós konfig gyorsan kétszáz sorosra hízik. Ez a sorrend segít, hogy később is megtaláld benne, amit keresel:

export default defineNuxtConfig({
  // 1. alapok
  compatibilityDate: '2026-08-01',
  srcDir: 'app',                      // Nuxt 4-ben ez az alapértelmezés
  devtools: { enabled: true },

  // 2. modulok — a sorrend SZÁMÍT, egymásra épülhetnek
  modules: ['@pinia/nuxt', '@nuxt/image', 'nuxt-auth-utils', '@nuxtjs/i18n'],

  // 3. amit az app tölt be
  css: ['~/assets/css/main.css'],

  // 4. auto-import finomhangolás (3. modul)
  components: [{ path: '~/components', pathPrefix: false }],
  imports: { dirs: ['composables/**'] },

  // 5. futásidejű értékek (12.2)
  runtimeConfig: { /* … */ },

  // 6. útvonal-viselkedés (7. modul)
  routeRules: { /* … */ },

  // 7. szerver és platform (2., 7., 11. modul)
  nitro: {
    preset: 'cloudflare_module',
    storage: { cache: { driver: 'cloudflare-kv-binding', binding: 'CACHE' } },
  },

  // 8. build-eszközök
  vite: { /* … */ },

  // 9. környezeti felülírások a végén — így látszik, mi tér el
  $development: { /* … */ },
  $production:  { /* … */ },
})

12.7TypeScript a Nuxt 4-ben

A Nuxt 4 nagy változása, hogy külön TypeScript-projekteket generál az app-, a szerver-, a megosztott és a builder-kódnak. Neked ehhez egyetlen fájlt kell karbantartanod:

// tsconfig.json — a gyökérben, ennyi
{
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ]
}

A haszna konkrét: a szerverkódban nem kapsz DOM-típusokat (tehát nem tudsz véletlenül document-et írni ott), az app-kódban pedig nem látszanak a Nitro-utilok. A 2. modul „melyik kódom hol fut” táblája így a fordító szintjén is érvényesül.

A bindingok típusai

npx wrangler types           # worker-configuration.d.ts a wrangler.jsonc alapján

// server/types/runtime-config.d.ts — hogy a runtimeConfig is típusos legyen
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    sessionPassword: string
    stripeSecretKey: string
    upstream: { baseUrl: string; token: string }
  }
  interface PublicRuntimeConfig {
    appName: string
    siteUrl: string
    stripePublicKey: string
  }
}
export {}

12.8Konfigurációs checklist

12.9Ellenőrizd magad