Modul-ökoszisztéma — Workers-szűrővel

13.1Mi az a Nuxt-modul valójában?

Nem sima npm-függőség, hanem build-időben lefutó kód, ami módosítja a projektedet: hozzáad fájlokat a virtuális fájlrendszerhez, regisztrál komponenseket és composable-öket, felvesz server route-okat, átírja a Vite- vagy a Nitro-konfigot.

Ebből három gyakorlati következmény adódik:

• A sorrend számít. A modulok egymás után futnak, és felülírhatják egymás beállításait. Ha valami megmagyarázhatatlanul nem érvényesül, először a sorrendet nézd meg.
• Egy modul lehet tisztán build-idejű — ilyenkor Workers-en semmi kockázata, mert futásidőben már nincs jelen. Vagy hozhat futásidejű kódot is (server route-ot, plugint) — ekkor számít, mit használ.
• A DevTools „Modules” füle megmutatja, mi futott le és milyen sorrendben. Ez a debug első lépése.

13.2A négy kérdés — a szűrő

Mielőtt beveszel egy modult, fusd át ezt a négyet. Öt perc, és megspórolja a „deploy után 500-as” estét:

13.3A megrostált lista

Amit szinte biztosan használni fogsz

Amit érdemes megfontolni

Amivel vigyázz

• Bármi, ami sharp-ot húz be. Képfeldolgozó, PDF-előnézet, thumbnail-generátor — a sharp natív addon, nem fut. Ha egy modul függőségei közt ott van, az nem konfigurálható meg.
• Szerveroldali dokumentum-generátorok (PDF, Excel, ODF). Vagy natív libet használnak, vagy nagyok, vagy CPU-igényesek — a 9. modul „hagyd kint” listájára valók.
• Modulok, amik .cache/-be írnak futásidőben. Fejlesztés közben működnek, élesben nem — a 2. modul dev-vs-prod táblája.
• Nuxt 2-es korszakból maradt modulok. A @nuxtjs/ névtérben van néhány, ami évek óta nem frissült. Nem attól rossz, hogy régi — attól, hogy a következő majornál te fogod javítani.

13.4@nuxt/image — a leggyakoribb Workers-buktató

Ez a modul kerül elő először, és itt esik szét először a „csak telepítem és megy” érzés.

Az @nuxt/image alapértelmezett providere (IPX) a szerveren dolgozza fel a képet — átméretez, formátumot vált, tömörít. Ehhez a sharp könyvtárat használja, ami natív addon. Workers-en ez nem opció, és nem is lesz az.

A jó hír: nem is kell, mert a Cloudflare ezt a réteget amúgy is adja. Két provider van:

// nuxt.config.ts — a zóna-alapú út
export default defineNuxtConfig({
  modules: ['@nuxt/image'],

  image: {
    provider: 'cloudflare',
    cloudflare: {
      baseURL: 'https://app.pelda.hu',   // a zónád — a /cdn-cgi/image/ automatikusan kerül elé
    },
    // a szokásos méret-készlet, hogy ne kelljen minden <NuxtImg>-nél megadni
    screens: { sm: 640, md: 768, lg: 1024, xl: 1280 },
  },
})

<template>
  <NuxtImg
    src="/uploads/acme/borito.jpg"
    width="960" height="540"
    sizes="sm:100vw md:50vw lg:960px"
    format="webp"
    loading="lazy"
  />
</template>

13.5@nuxt/content — megy, de tudni kell, hogyan

A Content v3 lecserélte a régi, fájlrendszer-alapú modellt egy SQL-alapúra, és ezzel serverless környezetben is működik: a tartalom build-időben adatbázisba kerül, futásidőben pedig onnan olvassa. Cloudflare-en ez D1.

Két dolgot érdemes tudni róla, mielőtt beveszed:

• Kell hozzá egy D1-adatbázis (vagy más támogatott tároló), és a tartalom-frissítés deployhoz kötött — ez blognál és dokumentációnál teljesen rendben van.
• A kliensoldali navigációhoz WASM SQLite töltődik be a böngészőbe. Ez gyors, de méret — és nálad a bundle-limit valós korlát. Mérd meg, mielőtt eldöntöd.

13.6Saját modul — mikor éri meg

Akkor, ha ugyanazt a setupot harmadszor másolod be egy projektbe, vagy ha több appod osztozik egy konvención. Egy modul váza meglepően rövid:

// modules/tenant-context.ts — a projekt gyökerében lévő modules/ automatikusan betöltődik
import { defineNuxtModule, addServerHandler, addImports, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'tenant-context', configKey: 'tenantContext' },
  defaults: { headerName: 'x-tenant' },

  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)

    // ① szerver middleware regisztrálása (4. modul)
    addServerHandler({
      middleware: true,
      handler: resolve('./runtime/server/tenant'),
    })

    // ② composable auto-importtal
    addImports({ name: 'useTenant', from: resolve('./runtime/composables/useTenant') })

    // ③ konfiguráció átadása a futásidőnek
    nuxt.options.runtimeConfig.public.tenantHeader = options.headerName
  },
})

13.7Modul-higiénia

• Mérj a bevétel előtt és után. A wrangler check startup (11.3) megmondja, mennyit nőtt a bundle és a hidegindítás. Egy modul, ami 300 KB-ot hoz egy ritkán használt funkcióért, rossz üzlet.
• Egy modul ne oldjon meg olyat, ami tíz sor. Ez a keretrendszer-ökoszisztémák klasszikus csapdája: a függőség karbantartási költsége nem nulla.
• A modulok sorrendjét dokumentáld, ha számít. Egy komment a modules tömbben többet ér, mint egy hónap múlva a kideríteni, miért nem érvényesül valami.
• Frissítés preview-deployjal. Ha egy modul minor verziót ugrik, az a build-folyamatot módosíthatja — a preview-URL az egyetlen hely, ahol ez valódi Workers-runtime alatt kiderül.

13.8Ellenőrizd magad