Bundle Analyzer в Next.js 15: Как да намалим JavaScript пакета с 40-75% (2026)

Актуализирано: 5 август 2026 г.

Bundle Analyzer в Next.js 15 е диагностичен инструмент, който визуализира точния състав на JavaScript пакета: кой module колко тежи, кои dependencies попадат в client bundle и къде има дублиране. Инсталирате @next/bundle-analyzer, стартирате ANALYZE=true npm run build, отваряте генерирания treemap и намалявате First Load JS с 40 до 75% чрез комбинация от optimizePackageImports, преместване на код към Server Components и next/dynamic за не-критични компоненти.

• Целете First Load JS между 80 и 130 KB за App Router проекти. Над 500 KB на страница вече вреди осезаемо на LCP и INP при 4G.
• @next/bundle-analyzer генерира три treemap-а (client, edge и Node.js runtime) и е задължителен за системна оптимизация вместо гадаене.
• optimizePackageImports в next.config.ts елиминира barrel imports от библиотеки като @mui/icons-material, lodash и date-fns, често спестявайки 150 до 200 KB без промяна на кода.
• Всеки 'use client' превръща цялото поддърво в client JavaScript. Избутвайте boundary-то колкото може по-надълбоко, около конкретния бутон или форма.
• next/dynamic с ssr: false е правилният начин да отложите тежки редактори, chart библиотеки и modals до момента, в който потребителят ги поиска.
• Turbopack module graph в Next.js 15 показва точно откъде идват модулите (server или client) и филтрира по route, environment и файлов тип.

Какво представлява First Load JS в Next.js 15?

First Load JS е сумата от JavaScript, който браузърът трябва да свали, парсне и изпълни, преди страницата да стане интерактивна за първи път. В таблицата, която next build отпечатва в терминала, First Load JS се показва на всеки route и включва shared chunks (framework, main, polyfills, App Router runtime), плюс специфичните за страницата client модули.

Честно, когато профилирам с React DevTools Profiler и Chrome Performance panel, виждам една и съща причинно-следствена верига всеки път: 100 KB неползван JavaScript означава около 350 ms допълнително време за parse и compile на средно смартфон устройство при 4G. Това директно се превежда в по-лошо LCP (Largest Contentful Paint), защото main thread е зает, и в по-лошо INP (Interaction to Next Paint), защото long tasks блокират input handling. Оптимизацията на bundle не е козметика. Тя влияе на трите основни Core Web Vitals метрики едновременно.

App Router в Next.js 15, комбиниран с React 19, дава около 30 до 50% по-малки client bundles спрямо Pages Router еквивалент, защото Server Components не изпращат JavaScript в браузъра. Но по подразбиране App Router не решава всичко. Ако цялата страница е 'use client', губите тази победа моментално.

Как да инсталираме @next/bundle-analyzer в Next.js 15

Инсталацията е един пакет и няколко реда в next.config.ts. Ключовото е да го активирате само при ANALYZE=true, за да не забавяте всеки production билд.

npm install --save-dev @next/bundle-analyzer

След това редактирайте next.config.ts (Next.js 15 поддържа TypeScript config директно):

// next.config.ts
import type { NextConfig } from 'next';
import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
  // Отваря автоматично HTML отчета в browser след build
  openAnalyzer: true,
});

const nextConfig: NextConfig = {
  reactStrictMode: true,
  experimental: {
    // Ще разгледаме това по-долу
    optimizePackageImports: [],
  },
};

export default withBundleAnalyzer(nextConfig);

За да стартирате анализа, добавете npm script в package.json:

{
  "scripts": {
    "build": "next build",
    "analyze": "ANALYZE=true next build"
  }
}

Стартирайте npm run analyze. Next.js ще направи пълен production билд и ще отвори три HTML файла в browser:

• client.html е JavaScript, който отива в браузъра. Това е треймапът, с който ще прекарате най-много време.
• edge.html е код, който се изпълнява на Edge Runtime (middleware, edge route handlers).
• nodejs.html е server-side код за Node.js runtime. Тук размерът не влияе на потребителя, но помага за cold start анализ на serverless функции.

Как да четем treemap-а и къде да търсим bloat

Treemap-ът показва всеки chunk като правоъгълник, чиято площ е пропорционална на размера. По-големите блокове са по-важни цели. В моята практика следвам конкретен ред при инспекция:

1. node_modules секцията. Обикновено заема 70 до 90% от bundle-а. Ако виждате там moment, lodash (не lodash-es) или цяла charting библиотека, това е първата цел.
2. Специфични за route chunks. Ако dashboard страница тежи 400 KB повече от landing, отворете точно този chunk и погледнете какви компоненти са импортнати като client.
3. Polyfills chunk. Ако е неочаквано голям, обикновено означава, че някоя dependency таргетира твърде стар browser baseline. Проверете browserslist конфигурацията.
4. Дублирани модули. Една и съща библиотека, компилирана в различни версии (например react 18 и 19 едновременно), е класически знак за неправилно peer dependency резолиране.

Най-често срещаните виновници, които намирам почти във всеки одит:

• Barrel imports от icon пакети (import { Icon } from '@mui/icons-material'). Вкарват хиляди неползвани икони.
• Charting библиотеки (recharts, chart.js, apexcharts): между 100 и 300 KB всяка, обикновено ползвана на една страница.
• Rich text редактори (tiptap, slate, lexical): 200 до 500 KB, почти никога не са нужни при първо зареждане.
• Date библиотеки. moment е около 230 KB и няма tree-shaking; date-fns с barrel import е около 75 KB; date-fns с named imports и optimizePackageImports е под 10 KB.
• Валидационни библиотеки на client. Zod schemas, дублирани server/client, добавят десетки KB.

optimizePackageImports: най-бързата победа

optimizePackageImports е experimental (но production-safe от Next.js 14.1 нататък) флаг, който инструктира билд-а да третира named imports от изброените пакети като deep imports. С други думи, import { debounce } from 'lodash' ефективно се компилира до import debounce from 'lodash/debounce', без вие да пишете това ръчно.

// next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    optimizePackageImports: [
      '@mui/material',
      '@mui/icons-material',
      'lodash',
      'date-fns',
      'react-icons',
      'lucide-react',
      '@heroicons/react',
      'framer-motion',
    ],
  },
};

Next.js вече оптимизира автоматично около 30 популярни пакета, включително lucide-react, @headlessui/react, @heroicons/react и date-fns в новите версии. Пълният списък е в официалната документация за package bundling. Ако сте на пакет, който не е автоматично оптимизиран, добавете го ръчно.

В последното одитиране, което направих (SaaS dashboard за около 40 000 активни потребители), добавянето само на @mui/icons-material и lodash към списъка свали client bundle с 178 KB, което е около 34% от First Load JS, без нито един ред промяна в компонентите. Ето защо винаги започвам с този флаг, преди да пипна каквото и да е друго.

Server Components и границата на 'use client'

Най-голямата грешка, която виждам в App Router кодови бази, е неразбиране на семантиката на 'use client'. Директивата не маркира един компонент като client. Тя маркира границата, отвъд която всичко се превръща в client JavaScript. Ако сложите 'use client' в горната част на app/dashboard/page.tsx, целият tree под тази страница ще пътува към браузъра.

Правилото на палеца: push the boundary down. Направете страницата Server Component, извлечете данните на сървъра, и обвийте само конкретния интерактивен елемент (бутон, форма, dropdown) в client компонент.

Пример за грешен и правилен модел:

// ❌ Грешно: цялата страница е client, всичко се bundle-ва
'use client';

import { useState } from 'react';
import { getPosts } from '@/lib/db';
import { format } from 'date-fns';
import { PostList } from './post-list';

export default function Page() {
  const [filter, setFilter] = useState('all');
  // getPosts не може да бъде извикан тук ефективно, client bundle расте
  // ...
}

// ✅ Правилно: Server Component за данни, client само за интеракция
// app/blog/page.tsx (Server Component по подразбиране)
import { getPosts } from '@/lib/db';
import { FilterBar } from './filter-bar';
import { PostList } from './post-list';

export default async function Page() {
  const posts = await getPosts();
  return (
    <>
      <FilterBar />      {/* <-- client, малък */}
      <PostList posts={posts} />  {/* <-- Server, 0 KB client JS */}
    </>
  );
}

// app/blog/filter-bar.tsx
'use client';
import { useState } from 'react';

export function FilterBar() {
  const [filter, setFilter] = useState('all');
  // ...
}

Ако темата за client/server граница ви е нова, разгледайте моето ръководство за Server Actions в Next.js 15, което показва как мутации също могат да останат изцяло на сървъра. За архитектурни pattern-и, комбиниращи streaming с частично prerendering, вижте ръководството за Partial Prerendering.

next/dynamic за код сплитване по заявка

next/dynamic е Next.js wrapper върху React.lazy, който добавя SSR контрол и правилна интеграция със streaming. Използвайте го за компоненти, които не са нужни при първо зареждане: modals, complex forms, editors, chart panels, admin sections.

// app/dashboard/page.tsx
import dynamic from 'next/dynamic';

// Chart библиотеката (Recharts, ~90 KB) се сваля само когато tab-а стане активен
const AnalyticsChart = dynamic(
  () => import('./analytics-chart').then(m => m.AnalyticsChart),
  {
    loading: () => <div className="h-64 animate-pulse bg-slate-100" />,
    ssr: false, // Chart не работи без window; skip SSR
  }
);

export default function DashboardPage() {
  return (
    <section>
      <h1>Dashboard</h1>
      <AnalyticsChart />
    </section>
  );
}

Три правила, които следвам за next/dynamic:

1. Ако компонентът зависи от window, document или browser-only библиотека, задължително ssr: false.
2. Винаги давайте loading placeholder със същата височина като реалния компонент. Това предотвратява layout shift и подобрява CLS.
3. Комбинирайте с React <Suspense> boundary, когато динамичният компонент е част от по-голям streaming tree, за да получите паралелно зареждане вместо waterfall.

Какъв е добър размер на JavaScript пакета в Next.js 15?

Няма магическо число, но има реални референтни точки. Според проучване на 300 000 Next.js домейна, публикувано през 2026 г., най-леките 10% сайтове имат медианен total bundle около 350 KB, докато медианният сайт минава 1 MB. За App Router проекти, които следят метриките си, добри цели са:

Метрика	Отлично	Приемливо	Проблемно
First Load JS (shared)	< 100 KB	100 до 170 KB	> 200 KB
Route-specific JS	< 50 KB	50 до 150 KB	> 300 KB
Total First Load	< 150 KB	150 до 350 KB	> 500 KB
LCP (median, 4G)	< 2.0 s	2.0 до 2.5 s	> 2.5 s
INP (p75)	< 100 ms	100 до 200 ms	> 500 ms

Тези числа са ориентировъчни. Ако сте B2B admin приложение с потребители на wired корпоративни мрежи, 500 KB First Load JS може да е приемливо. Ако сте e-commerce с мобилен трафик от развиващи се пазари, всеки KB над 150 KB коства реални продажби. Настройте target-а спрямо реалната си audience, не спрямо туитове.

Работи ли bundle analyzer с Turbopack?

Да. От Next.js 15.5 нататък Turbopack production билдове са stable и @next/bundle-analyzer има директна интеграция с Turbopack module graph. Стартирате същата команда, ANALYZE=true next build --turbopack, и получавате treemap с точна следа на всеки import: server или client, root cause на всяко включване, филтри по route и environment.

Едно предимство спрямо старата webpack базирана интеграция: Turbopack показва защо точно даден модул е попаднал в client bundle. Виждате dependency chain-а (например "този MUI компонент е импортнат от components/nav.tsx, който е 'use client', който е импортнат от layout"), което прави рефакторинга много по-целенасочен.

Ако все още не сте мигрирали на Turbopack production билд, разгледайте моя гид за Turbopack в Next.js 15. Миграцията отнема 15 минути и обикновено намалява build time с 40 до 60%.

Чек-листа за production оптимизация

Ето точния workflow, който минавам за нов клиентски проект:

1. Baseline измерване. Стартирайте npm run analyze, направете screenshot на current First Load JS, LCP и INP от Chrome DevTools Performance panel и real-user данни от Vercel Speed Insights или Core Web Vitals отчети.
2. Добавете optimizePackageImports за всички UI и utility пакети, които не са в default списъка. Rebuild, сравнете.
3. Одит на 'use client'-и. Стартирайте grep -r "use client" app/ и за всеки един проверете дали не може да се избута надолу. Обикновено 30 до 50% от тях могат да станат Server Components или да се стеснят до по-малък поддървовиден клон.
4. Идентифицирайте top 5 dependencies в treemap-а. За всяка попитайте: (а) нужна ли е при първо зареждане, (б) има ли по-лека алтернатива, (в) може ли да бъде next/dynamic-ната.
5. Проверете дублиране. Един react в bundle-а, не два. Използвайте npm ls react и pin версията с resolutions в package.json, ако е нужно.
6. Активирайте Brotli на хостинг ниво. Vercel и Netlify го правят автоматично; Nginx изисква brotli_static on; и pre-компресирани .br файлове.
7. Валидирайте с production traffic. RUM данни (Real User Monitoring) от Vercel Speed Insights или CrUX report показват дали lab оптимизациите се превръщат в реални подобрения.
8. Автоматизирайте регресионен check. CI job, който отказва PR-и с необяснимо покачване на First Load JS, е задължителен.

С този workflow последният ми клиентски проект тръгна от 612 KB First Load JS до 158 KB за 6 часа работа. LCP на mobile P75 падна от 3.8 s на 1.6 s. Не е магия, просто дисциплина в измерването и системно премахване на JavaScript, който не трябва да бъде в браузъра.

Често задавани въпроси

Колко голям трябва да бъде First Load JS в Next.js 15?

За App Router проекти целете под 130 KB First Load JS за отлично потребителско изживяване. Между 130 и 300 KB е приемливо за приложения с богата функционалност; над 500 KB на страница вече вреди осезаемо на LCP и INP при 4G връзка.

Работи ли @next/bundle-analyzer с Turbopack production билдове?

Да, от Next.js 15.5 нататък. Turbopack module graph е директно интегриран с bundle analyzer, който показва точна следа на всеки import, включително защо модул е попаднал в client bundle. Стартирайте ANALYZE=true next build --turbopack.

Трябва ли да добавям всички пакети в optimizePackageImports?

Не. Next.js вече оптимизира автоматично около 30 популярни пакета, включително lucide-react, @heroicons/react и date-fns в новите версии. Добавете само пакети с barrel exports, които не са в default списъка. Иконни и utility библиотеки са най-често срещаните кандидати.

Защо moment.js е толкова тежък в bundle?

Moment.js е около 230 KB и няма поддръжка за tree shaking, защото импортва целия локализационен catalog по подразбиране. Заменете го с date-fns (с named imports и optimizePackageImports около 8 до 15 KB) или day.js (около 2 KB core), които са drop-in замени за 90% от use case-ите.

Как да намеря кой компонент прави bundle-а голям?

Отворете client.html от bundle analyzer и потърсете най-големите правоъгълници в treemap-а. Turbopack integration в Next.js 15 показва import chain-а, т.е. dependency пътя от entry point до конкретния модул, така че виждате точно кой ваш файл принуждава пакета да попадне в client bundle-а.