Bundle Size & Tree-shaking

Optimize your bundle size by choosing the right approach for your use case.

Import strategies overview

1. Named Imports

Best for: Static flags known at build time
Bundle impact: ~950 bytes per flag
Tree-shaking: ✅ Excellent
Loading: Synchronous, instant

View detailed usage with code examples →

2. DynamicFlag

Best for: Offline-first apps that must render any runtime code synchronously
Bundle impact: ~600 KB (all flags bundled)
Tree-shaking: ❌ None
Loading: Synchronous, instant

View detailed usage with code examples →

Bundle size comparison

Method	Bundle Size	Tree-shaking	Loading	Use Case
Named imports (3 flags)	~2.8 KB	✅ Excellent	Instant	Known flags at build time
Named imports (10 flags)	~9.5 KB	✅ Excellent	Instant	Common flags header
DynamicFlag	~600 KB	❌ None	Instant	CDN-restricted, all flags needed

Expected bundle sizes

Performance tips

Code Splitting

Split flag components across routes to load only what’s needed per page.

Lazy Loading

Use your framework’s lazy loading (React lazy(), Vue defineAsyncComponent, Solid lazy()) to defer flags until they’re actually rendered.

Static Analysis

Run bundle analysis regularly to catch unexpected size increases.

Prefer Offline-first

Default to named imports. If you must support any runtime code synchronously, use DynamicFlag.

Analyzing your bundle

Use these tools to verify your bundle size:

# Webpack Bundle Analyzer
npm install --save-dev webpack-bundle-analyzer

# Vite Bundle Analyzer
npm install --save-dev rollup-plugin-visualizer

# Next.js Bundle Analyzer
npm install --save-dev @next/bundle-analyzer

Basic Usage Learn how to import and use flag components with code examples

Dynamic Flags Offline-first strategies for runtime ISO codes