code-splitting

name	code-splitting
description	Reduce initial bundle size with dynamic imports, React.lazy, route-based splitting, component-level splitting, and bundle analysis — faster load times through strategic chunking
layer	domain
category	performance
triggers	["code splitting","dynamic import","React.lazy","lazy load","bundle size","bundle analysis","chunk","tree shaking","initial load time","reduce bundle"]
inputs	["Framework (React, Next.js, Vue, Svelte)","Build tool (Vite, webpack, Turbopack)","Current bundle size and performance metrics","Route structure and component hierarchy","Critical vs. non-critical features"]
outputs	["Code splitting strategy with chunk boundaries","Dynamic import implementation for routes and components","Suspense boundaries with loading states","Bundle analysis report and optimization recommendations","Preloading and prefetching strategy for split chunks"]
linksTo	["web-workers","performance-profiler","react","nextjs"]
linkedFrom	["optimize","performance-profiler"]
preferredNextSkills	["performance-profiler","web-workers"]
fallbackSkills	["optimize"]
riskLevel	low
memoryReadPolicy	selective
memoryWritePolicy	none
sideEffects	[]

Code Splitting Skill

Purpose

Code splitting breaks a monolithic JavaScript bundle into smaller chunks loaded on demand. Instead of shipping 2MB of JavaScript upfront — most of which the user may never need — you load only the code required for the current view and defer the rest. This directly improves Time to Interactive (TTI), Largest Contentful Paint (LCP), and Total Blocking Time (TBT).

Key Concepts

Splitting Strategies

Strategy	Granularity	Best For
Route-based	Per page/route	SPAs with distinct pages
Component-based	Per feature/widget	Heavy components (editor, chart, map)
Library-based	Per vendor package	Large dependencies (moment, lodash, d3)
Interaction-based	On user action	Features triggered by click/hover
Viewport-based	On scroll into view	Below-the-fold content

How Dynamic Imports Work

Static import:
  import { heavyFn } from './heavy'; // Included in main bundle ALWAYS

Dynamic import:
  const { heavyFn } = await import('./heavy'); // Separate chunk, loaded on demand

Bundler sees dynamic import → creates separate chunk → loads via <script> tag at runtime

Critical Path vs. Lazy Path

CRITICAL (load immediately):
  - App shell / layout
  - Current route's above-the-fold content
  - Authentication state
  - Design system primitives (Button, Input)

LAZY (load on demand):
  - Other routes
  - Modals, dialogs, drawers
  - Admin panels, settings pages
  - Heavy editors (rich text, code editor)
  - Charts, data visualization
  - PDF/export functionality

Implementation

React.lazy + Suspense (Route-Based)

import { Suspense, lazy } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// Each lazy() call creates a separate chunk
  = ( ());
  = ( ());
  = ( ());
  = ( ());

 () {
   (
    
  );
}

   () {
   (
    
  );
}