BUNDLE OPTIMIZATION

Bundle Optimization Guide¶

Date: 2026-01-14 Cycle: C-180+ Status: Optimized

Executive Summary¶

The Mobius Substrate monorepo has been optimized for bundle size across all Next.js applications. This document provides guidelines for maintaining optimal bundle sizes and avoiding common pitfalls.

Current Optimizations¶

✅ Three.js Components (600KB library)¶

Status: Fully Optimized Impact: ~600KB saved on initial page load

integrity-pulse App¶

All 3D visualization components use Next.js dynamic() imports with ssr: false:

// apps/integrity-pulse/src/app/page.tsx
const MultiAgentGrid = dynamic(
  () => import('@/components/MultiAgentGrid'),
  { ssr: false }
);

// apps/integrity-pulse/src/app/sacred/page.tsx
const SacredViz = dynamic(
  () => import('@/components/SacredViz'),
  { ssr: false }
);

Components optimized: - MultiAgentGrid.tsx (uses react-three/fiber + react-three/drei) - SacredViz.tsx (uses Three.js) - SentinelSphere.tsx (used by MultiAgentGrid) - GeometryCanvas.tsx - SacredPulse3D.tsx

Result: Three.js and related 3D libraries (~600KB) are: - Not included in initial bundle - Only loaded when user navigates to pages using 3D visualizations - Not processed during SSR (prevents server-side errors)

✅ Builder.io CMS Components (150KB)¶

Status: Optimized with Loading States Impact: Better perceived performance

Files: - apps/mobius-landing/app/page.tsx - apps/mobius-landing/app/[...page]/page.tsx

Why not lazy-loaded: Builder.io is used on the homepage and all dynamic pages. Lazy-loading would delay content rendering. Instead, we've: - Added proper loading skeletons - Improved error states - Used client-side data fetching

Trade-off: Builder.io must be in the main bundle for homepage, but provides CMS flexibility.

✅ Lucide React Icons¶

Status: Optimized (Tree-shakeable) Impact: ~40KB gzipped for typical usage

Pattern (Correct):

// ✅ Good - named imports
import { Scale, Sparkles, Shield } from 'lucide-react';

Anti-pattern:

// ❌ Bad - would import entire library
import * as Icons from 'lucide-react';

Usage: 11 files across portal and aurea-site apps Status: All using named imports correctly ✓

✅ Ethers.js (Crypto Library)¶

Status: Correctly Placed Impact: 0KB client bundle impact

Pattern:

// ✅ Good - only in API routes (server-side)
// apps/hub-web/pages/api/civic/resolve.ts
import { ethers } from "ethers";

Result: Ethers.js runs server-side only, not included in client bundle.

Bundle Size Targets¶

Best Practices¶

1. Heavy Libraries (>100KB)¶

Always use next/dynamic with ssr: false for: - 3D libraries (Three.js, @react-three/*) - Chart libraries (Chart.js, Recharts) - Rich text editors - PDF viewers - Image/video processing libraries

Template:

import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(
  () => import('./HeavyComponent'),
  {
    ssr: false,
    loading: () => <LoadingSkeleton />
  }
);

2. Icon Libraries¶

DO: - Use named imports: import { IconName } from 'library' - Prefer tree-shakeable libraries (lucide-react, react-icons)

DON'T: - Import entire icon set: import * as Icons from 'library' - Use icon fonts (not tree-shakeable)

3. Date Libraries¶

DO: - Use native Date API when possible - Use date-fns with specific imports: import { format } from 'date-fns'

DON'T: - Use moment.js (deprecated, 200KB+) - Import entire lodash: import _ from 'lodash'

4. Utility Libraries¶

Pattern:

// ✅ Good - specific imports
import { map, filter } from 'lodash-es';

// ❌ Bad - entire library
import _ from 'lodash';

5. CSS-in-JS Libraries¶

If using styled-components, emotion, etc.: - Enable babel plugins for SSR - Use styled-components/macro for better tree-shaking - Consider CSS Modules or Tailwind as lighter alternatives

Analysis Tools¶

Check Bundle Size¶

# Build and analyze
npm run build --workspace=apps/portal

# Use Next.js built-in analyzer
ANALYZE=true npm run build --workspace=apps/portal

Webpack Bundle Analyzer¶

Add to next.config.js:

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // ... rest of config
});

Lighthouse¶

# Run Lighthouse in CI
npx lighthouse https://your-app.vercel.app --view

Code Splitting Strategies¶

Route-based Splitting¶

Next.js automatically splits by route:

pages/
  index.tsx          → chunk-index.js
  dashboard.tsx      → chunk-dashboard.js
  profile.tsx        → chunk-profile.js

Component-based Splitting¶

For large components:

const DashboardStats = dynamic(() => import('./DashboardStats'));
const UserProfile = dynamic(() => import('./UserProfile'));

Conditional Splitting¶

Load features only when needed:

// Load admin panel only for admins
const AdminPanel = dynamic(() => import('./AdminPanel'));

function Dashboard({ user }) {
  return (
    <>
      <MainContent />
      {user.isAdmin && <AdminPanel />}
    </>
  );
}

Import Audit Checklist¶

Before adding a new dependency, check:

• Size: Is it <50KB gzipped?
• Tree-shakeable: Does it support ESM imports?
• Alternatives: Are there lighter alternatives?
• Usage: Is it used on every page or just specific routes?
• SSR: Does it work with Next.js SSR?

Dependency Size Check¶

# Check package size before installing
npx bundle-phobia <package-name>

# Example
npx bundle-phobia three
# three@0.160.0 - 600KB (186KB gzipped)

Common Anti-Patterns¶

❌ Import Entire Library¶

// Bad - imports entire lodash (~70KB)
import _ from 'lodash';
_.map(array, fn);

// Good - imports only map function
import { map } from 'lodash-es';
map(array, fn);

❌ Client-Side Heavy Processing¶

// Bad - large library on client
import pdfMake from 'pdfmake';

function generatePDF() {
  // Generates PDF client-side
}

// Good - move to API route
async function generatePDF() {
  const response = await fetch('/api/generate-pdf', {
    method: 'POST',
    body: JSON.stringify(data)
  });
  return response.blob();
}

❌ Import Namespace for Three.js in Non-Pages¶

// Acceptable only in components that are dynamically imported
import * as THREE from 'three';

Note: import * as THREE is the standard pattern for Three.js, but components using it must be dynamically imported.

Monitoring¶

CI/CD Integration¶

Add bundle size checks to GitHub Actions:

# .github/workflows/bundle-size.yml
- name: Check bundle size
  run: |
    npm run build --workspace=apps/portal
    npx bundlewatch

Bundle Budget¶

Set budgets in next.config.js:

module.exports = {
  performance: {
    maxInitialRequests: 25,
    maxAssetSize: 300000, // 300KB
  }
};

Performance Budgets¶

Current Targets¶

Future Optimizations¶

Potential Improvements¶

1. React Server Components (Next.js 13+)
2. Move more logic to server components

3. Reduce client-side JavaScript

4. Partial Hydration

5. Hydrate only interactive components

6. Keep static content as HTML

7. Edge Functions

8. Move API logic to edge for faster responses

9. Reduce serverless cold starts

10. Image Optimization

11. Use Next.js Image component everywhere
12. Implement AVIF format support
13. Add blur placeholders

Related Documentation¶

• PERFORMANCE_ANALYSIS.md - Full performance audit
• CLAUDE.md - Project structure and commands
• Next.js Bundle Analysis: https://nextjs.org/docs/advanced-features/measuring-performance

Maintained by: ATLAS Agent Last Updated: C-180+ Bundle Optimization (2026-01-14)

"We optimize as we scale." — Mobius Substrate 🌀