Jak analizować i zmniejszyć paczkę JS w Next.js?

Dlaczego rozmiar pakietu JavaScriptu w Next.js ma znaczenie?

Next.js automatycznie dzieli kod na osobne pakiety per route (code splitting), ale nie zapewni to ochrony przed importowaniem całego lodash zamiast jednej funkcji, ciężkimi bibliotekami UI w każdym Client Component i zależnościami, które powinny zostać na serwerze.

Zacznij od granicy 'use client'

Dyrektywa 'use client' wyznacza granicę między grafem modułów serwera i klienta. Wszystko, co importuje Client Component, może trafić do paczki klienta. Dlatego nie oznaczaj nią całego layoutu lub strony tylko dlatego, że zawierają jeden interaktywny element. Zostaw stronę jako Server Component, a 'use client' umieść w małym komponencie formularza, wyszukiwarki czy przycisku.

Krok 1: zmierz pakiet JavaScriptu wbudowanym analizatorem Next.js

W Next.js 16.1+ analizator Turbopacka pozwala filtrować moduły po trasie i środowisku (klient lub serwer), a także prześledzić pełny łańcuch importów. To najlepszy punkt startu w projekcie korzystającym z domyślnego bundlera:

npx next experimental-analyze

Do porównania raportu przed i po optymalizacji zapisz go na dysku:

npx next experimental-analyze --output

Raport trafi do .next/diagnostics/analyze. Nie powstaje przy tym artefakt produkcyjnego buildu, więc standardowy npm run build nadal uruchom osobno przed wdrożeniem.

Alternatywa: @next/bundle-analyzer dla Webpacka

Jeśli projekt jest nadal budowany Webpackiem albo chcesz porównać jego raport, użyj wtyczki @next/bundle-analyzer:

npm install -D @next/bundle-analyzer

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {}
 
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
 
module.exports = withBundleAnalyzer(nextConfig)

# Uruchom build przez Webpack i otwórz raport
ANALYZE=true npm run build -- --webpack

Wtyczka otworzy osobne raporty dla pakietów klienta, serwera i edge runtime. Nie traktuj jednak wyniku Webpacka jako dokładnego odpowiednika buildu Turbopacka: do optymalizacji produkcyjnej analizuj przede wszystkim bundler używany przez projekt.

Czego szukać w analizie paczek kodu Next.js?

Duże biblioteki w pakiecie klienta

Typowi winowajcy:

Nie zakładaj, że zamiana jednej biblioteki na drugą automatycznie zmniejszy wynik. Rozmiar zależy od wersji, sposobu importu, użytych funkcji i pozostałych zależności. Zawsze porównaj raport przed i po zmianie.

Biblioteki serwerowe przypadkiem wrzucone do pakietu klienta

To najgroźniejszy przypadek, ponieważ jeśli w pakiecie klienta widzisz prisma, bcrypt, stripe albo @aws-sdk, kod serwerowy przedostał się do grafu klienta. Część takich importów zakończy build błędem, a inne niepotrzebnie zwiększą paczkę lub ujawnią nieprzeznaczony dla przeglądarki kod. Zwykle chodzi o jeden plik, importowany i przez Server, i przez Client Component.

// ŹLE — jeden plik miesza kod klienta i serwera
// utils.ts
import bcrypt from 'bcrypt'
 
export function formatDate(date: Date) {
  return new Intl.DateTimeFormat('pl-PL').format(date)
}
 
export function hashPassword(password: string) {
  return bcrypt.hash(password, 12)
}

Rozwiązanie: rozdziel na osobne pliki:

lib/
├── utils-client.ts    ← formatDate, formatPrice
└── utils-server.ts    ← hashPassword, db queries

Lub użyj server-only package:

npm install server-only

// lib/utils-server.ts
import 'server-only' // Błąd, jeśli moduł zaimportuje Client Component
import bcrypt from 'bcrypt'
 
export function hashPassword(password: string) {
  return bcrypt.hash(password, 12)
}

Krok 2: optymalizacja pakietu JavaScriptu w Next.js

Dynamiczny import i leniwe ładowanie ciężkich komponentów

'use client'
 
import { useState } from 'react'
import dynamic from 'next/dynamic'
 
const CodeEditor = dynamic(() => import('@/components/code-editor'), {
  ssr: false,
  loading: () => <p>Ładowanie edytora...</p>,
})
 
export function EditorPanel() {
  const [isEditorOpen, setIsEditorOpen] = useState(false)
 
  return (
    <section>
      <button onClick={() => setIsEditorOpen(true)}>Edytuj kod</button>
      {isEditorOpen && <CodeEditor />}
    </section>
  )
}

dynamic() wydziela komponent do osobnego pliku JavaScriptu. Żeby odroczyć jego pobranie, renderuj go dopiero wtedy, gdy użytkownik go potrzebuje, jak w przykładzie po kliknięciu. Samo ssr: false wyłącza renderowanie na serwerze, ale nie oznacza automatycznie ładowania po interakcji.

Tree shaking: importuj tylko potrzebny kod

Tree shaking usuwa z pakietu kod, którego nie używasz — ale tylko wtedy, gdy importujesz w sposób, który mu na to pozwala.

// ŹLE — importuje cały lodash
import _ from 'lodash'
_.debounce(fn, 300)
 
// DOBRZE — importuje jedną funkcję
import debounce from 'lodash/debounce'
debounce(fn, 300)
 
// NAJLEPIEJ — natywny JS, gdy naprawdę wystarcza prosty debounce
function debounce<TArgs extends unknown[]>(
  fn: (...args: TArgs) => void,
  ms: number,
) {
  let timer: ReturnType<typeof setTimeout>
  return (...args: TArgs) => {
    clearTimeout(timer)
    timer = setTimeout(() => fn(...args), ms)
  }
}

// ŹLE — importuje cały pakiet ikon
import * as Icons from 'lucide-react'
 
// DOBRZE — importuje jedną ikonę
import { Search } from 'lucide-react'

Next.js ma tu wbudowanego, eksperymentalnego pomocnika: optimizePackageImports. Dla wskazanych pakietów kompilator przepisuje import z barrela na bezpośrednie importy plików, więc nazwany import z ogromnej biblioteki przestaje ryzykować wciągnięciem całości. Popularne pakiety (m.in. lucide-react, date-fns, lodash-es, @mui/icons-material) są optymalizowane automatycznie — własne dopisujesz w konfiguracji:

// next.config.ts
const nextConfig = {
  experimental: {
    optimizePackageImports: ['moja-biblioteka-ui'],
  },
}

Barrel files we własnym kodzie: sprawdź, czy nie utrudniają tree shakingu

Barrel file — index.ts re-eksportujący wszystko z katalogu — daje krótkie importy. Przy czystych modułach ESM bundler zwykle usunie nieużywane eksporty. Sprawdź go jednak, gdy mapa drzewa pokazuje kod niepotrzebny na danej trasie: efekty uboczne, CommonJS lub nieoptymalny graf importów mogą uniemożliwić bezpieczne wycięcie modułu.

// components/index.ts — wygodny barrel
export { Button } from './button'
export { Card } from './card'
export { RevenueChart } from './revenue-chart' // ciężki: recharts w środku
export { PdfPreview } from './pdf-preview' // ciężki: pdf.js w środku

// Strona kontaktu potrzebuje tylko przycisku...
import { Button } from '@/components'
// Jeśli którykolwiek moduł ma efekty uboczne, bundler może nie usunąć
// RevenueChart i PdfPreview z paczki klienta.

optimizePackageImports działa tylko dla pakietów z node_modules — własnych barreli nie zmienia. Reguła praktyczna: gdy ciężka zależność pojawia się na trasie, która jej nie używa, zaimportuj komponent bezpośrednio z pliku i porównaj raport. Nie zakładaj jednak, że każdy barrel jest błędem: decyduje wynik analizy, nie sam styl importu.

Jak sprawdzić rozmiar zależności przed instalacją?

Zanim pakiet trafi do package.json, sprawdź, ile waży: bundlephobia.com pokazuje rozmiar po minifikacji i gzipie, koszt per wersja i to, czy pakiet wspiera tree shaking. Jak dla mnie, najwygodniejsze jest rozszerzenie VS Code Import Cost, które wyświetla rozmiar każdego importu bezpośrednio w edytorze. Dzięki temu ciężkie zależności zauważysz już w momencie ich dodawania, zamiast wykrywać je z opóźnieniem podczas analizy drzewa paczki.

Server Components i redukcja JavaScriptu w pakiecie klienta

W ramach optymalizacji, najlepiej przenieść logikę z Client na Server Components. Własny kod Server Component i używane przez niego biblioteki nie są wysyłane jako JavaScript do hydratacji, choć odpowiedź nadal zawiera wyrenderowany HTML i dane RSC potrzebne Reactowi.

// app/products/product-list.client.tsx
// PRZED — Client Component z useEffect (dodaje JS do paczki klienta)
'use client'
import { useState, useEffect } from 'react'
 
type Product = { id: string; name: string }
 
function ProductList() {
  const [products, setProducts] = useState<Product[]>([])
  useEffect(() => {
    fetch('https://api.example.com/products')
      .then((r) => r.json())
      .then(setProducts)
  }, [])
  return products.map((p) => <div key={p.id}>{p.name}</div>)
}

// app/products/product-list.tsx
import { getProducts } from '@/lib/products'
 
// PO — Server Component (bez własnego JavaScriptu do hydratacji)
export default async function ProductList() {
  const products = await getProducts()
  return products.map((p) => <div key={p.id}>{p.name}</div>)
}

Krok 3: pilnuj budżetu rozmiaru pakietu w CI/CD

Najpierw zapisz raport dla ważnych tras i ustal wartość bazową. Budżet powinien dotyczyć konkretnego artefaktu lub grupy plików, które chcesz kontrolować, a nie przypadkowego rozmiaru całego katalogu .next.

Przykład z size-limit dla wygenerowanych plików klienta:

npm install -D size-limit @size-limit/file

// package.json
{
  "scripts": {
    "size": "npm run build && size-limit"
  },
  "size-limit": [
    {
      "name": "client chunks",
      "path": ".next/static/chunks/**/*.js",
      "limit": "200 kB"
    }
  ]
}

Dodaj ten skrypt do pipeline'u CI/CD:

# .github/workflows/bundle-check.yml
- name: Build and check bundle
  run: npm run size

size-limit zakończy zadanie błędem po przekroczeniu limitu. Jeśli potrzebujesz kontroli konkretnych tras lub różnicy względem gałęzi bazowej, użyj raportu analizatora, bundlewatch albo narzędzia dopasowanego do platformy wdrożeniowej.

Jak oceniać wynik analizy?

Nie porównuj tras tylko po jednej liczbie kilobajtów. W raporcie odpowiedz kolejno na trzy pytania:

1. Czy ciężki moduł jest w paczce klienta, choć mógł pozostać na serwerze?
2. Czy jest potrzebny przy pierwszym renderze, czy można załadować go po interakcji?
3. Który import wprowadza go na trasę?

Po zmianie wygeneruj drugi raport i sprawdź rzeczywisty efekt w Lighthouse lub na danych RUM. Analiza pakietu pokazuje przyczynę, ale nie zastępuje pomiaru czasu ładowania, interaktywności i Core Web Vitals na urządzeniach użytkowników.