Nextjs Package Bundling Transpile Packages Server External Optimize

Definisi

Next.js mengelola bundling dependency lewat opsi seperti transpilePackages (compile ulang paket yang belum ESNext), serverExternalPackages (biarkan dependency tertentu tidak dibundle di server), dan optimasi import. Tujuannya: kompatibilitas + bundle size wajar.

Kapan dipakai

• transpilePackages: saat pakai lib yang masih pakai JSX/TS tapi belum di-build (misal design system internal).
• serverExternalPackages: pakai native module (sharp, sqlite) yang tidak boleh di-bundle di runtime server.
• optimizePackageImports: kurangi waktu compile dengan impor parsial otomatis.

Cara kerja

js

// next.config.js
module.exports = {
  transpilePackages: ['@kirem/ui', 'lodash-es'],
  serverExternalPackages: ['sharp', 'bcrypt'],
  experimental: {
    optimizePackageImports: ['lucide-react', 'date-fns'],
  },
};

Struktur alur

Catatan implementasi

• serverExternalPackages (dulu serverComponentsExternalPackages) mencegah error native module di edge/node.
• Terlalu banyak transpilePackages memperlambat build; hanya daftar yang perlu.
• optimizePackageImports otomatis tree-shake lib besar; cek daftar supported.
• Untuk monorepo, path alias + transpilePackages sering dipakai bareng.

Kesalahan umum

• Native module dibundle: error "cannot find module" di production; pindahkan ke serverExternalPackages.
• Transpile semua: build lambat sia-sia.
• Lib ESM di CJS unexpected: kadang perlu transpilePackages agar jalan.
• Lupa restart dev: perubahan config butuh restart.

Referensi terkait

• Next.js Static Generation, SSR, ISR, Dynamic Rendering
• Next.js Instrumentation, Middleware Auth, Edge vs Node
• TypeScript Project Organization: Monorepo, tsconfig inheritance