7a336e6e/frontend-landing/bundling-frontend

Bundling Frontend — Optimisation & Deployment

Ship a 60 fps storybook experience that loads fast on 3G, scores 90+ on Lighthouse, and deploys in one command.

---

Overview

An animation-heavy, full-screen landing page has specific bundling concerns that differ from a typical content site:

| Concern | Why It Matters | | ------------------------ | -------------------------------------------------- | | JS bundle size | Framer Motion + React can push past 150 kB gzipped | | CSS payload | Hundreds of keyframes and utility classes | | First paint speed | Intro animation must start within ~1.5 s | | Hydration cost | Full "use client" tree hydrates on load | | Asset loading | Images, fonts, icons must not block the intro |

---

1 — "use client" Boundary Strategy

The Rule

Push the "use client" boundary as low as possible.

app/
  layout.tsx          ← Server Component (metadata, fonts, analytics scripts)
  page.tsx            ← Server Component (renders the client journey)
  
components/
  seer/
    seer-journey.tsx  ← "use client" — the single interactive root

Only the storybook orchestrator and its children need to be client components. Everything above it (layout, metadata, font loading) stays on the server.

Anti-Pattern

// ❌ Don't mark layout.tsx as "use client" just because a child needs it
"use client"; // app/layout.tsx — wastes server rendering

Why This Matters

• Server Components don't ship JS to the client
• The layout renders static HTML (fonts, meta tags, body wrapper)
• Only the interactive journey ships as a client bundle

---

2 — Code Splitting & Dynamic Imports

Split Heavy Scenes

If certain scenes use large libraries (e.g., a chart library, 3D renderer), lazy-load them:

import dynamic from "next/dynamic";

const StatsScene = dynamic(() => import("./scenes/stats-scene"), {
  loading: () => <SceneSkeleton />,
  ssr: false, // No SSR for animation-heavy components
});

const DemoScene = dynamic(() => import("./scenes/demo-scene"), {
  loading: () => <SceneSkeleton />,
  ssr: false,
});

When to Split vs Inline

| Scenario | Recommendation | | --------------------------------- | ----------------------- | | Scene uses only Tailwind + motion | Keep inline (no split) | | Scene imports a chart / 3D lib | dynamic() import | | Scene has a heavy embed (iframe) | dynamic() + ssr: false | | Mascot with pupil tracking only | Keep inline |

Framer Motion Tree Shaking

Import only what you use — framer-motion supports deep imports:

// ✅ Good — tree-shakeable
import { motion, AnimatePresence } from "framer-motion";

// ❌ Bad — pulls entire library (older pattern)
import * as Motion from "framer-motion";

As of framer-motion v11+, the main entry point is already tree-shakeable, but avoid importing *.

---

3 — CSS Optimisation

Tailwind Purging

Tailwind's JIT compiler only includes classes you actually use. Ensure content paths cover all component files:

// tailwind.config.ts
const config: Config = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  // …
};

CSS-Only Animations Over JS Animations

Prefer CSS @keyframes for anything that runs continuously or on non-interactive elements (backgrounds, ambient effects):

| Animation Type | CSS or JS? | Reason | | --------------------- | ---------------- | ------------------------------- | | Typewriter text | CSS clip-path | Zero re-renders | | Floating particles | CSS @keyframes | Offloaded to compositor | | Pulse / glow loops | CSS @keyframes | No JS overhead | | Scene transitions | Framer Motion | Needs AnimatePresence logic | | Scroll-linked effects | Framer Motion | Needs useScroll / useMotionValue | | Mascot eye tracking | JS (ref-based) | Needs pointer position |

will-change for Composited Layers

Apply will-change to elements that animate transform or opacity:

.scene-container {
  will-change: transform, opacity;
}

.mascot-eye {
  will-change: transform;
}

⚠️ Don't apply will-change to everything — it consumes GPU memory. Only use it on elements that actually animate.

Reducing Paint with contain

.scene-page {
  contain: layout style paint;
}

This tells the browser that the scene is self-contained, reducing paint calculations when other parts of the DOM change.

---

4 — Font Loading Strategy

Use next/font for Zero-FOUT Loading

// app/layout.tsx
import { Inter, JetBrains_Mono } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  display: "swap",
  variable: "--font-sans",
});

const mono = JetBrains_Mono({
  subsets: ["latin"],
  display: "swap",
  variable: "--font-mono",
});

export default function RootLayout({ children }) {
  return (
    <html className={`${inter.variable} ${mono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

• next/font self-hosts fonts (no external requests)
• display: "swap" shows fallback text immediately
• CSS variables let Tailwind reference them:

// tailwind.config.ts
fontFamily: {
  sans: ["var(--font-sans)", ...fontFamily.sans],
  mono: ["var(--font-mono)", ...fontFamily.mono],
},

---

5 — Image & Asset Optimisation

Icons: Lucide React (Tree-Shakeable SVGs)

// ✅ Import individual icons
import { Shield, Brain, Eye } from "lucide-react";

// ❌ Don't import the whole set
import * as Icons from "lucide-react";

Each icon is ~200 bytes gzipped. Importing only what you need keeps the bundle small.

Background Images / Gradients

Prefer CSS gradients over raster images for backgrounds:

/* ✅ Zero network requests, infinitely scalable */
.hero-bg {
  background: radial-gradient(
    ellipse at 30% 50%,
    rgba(0, 212, 170, 0.08) 0%,
    transparent 60%
  );
}

/* ❌ Adds a network request and is fixed resolution */
.hero-bg {
  background-image: url("/hero-bg.png");
}

If You Must Use Images

import Image from "next/image";

<Image
  src="/product-preview.png"
  alt="Product dashboard"
  width={800}
  height={500}
  priority={false} // Only priority for above-the-fold
  placeholder="blur"
  blurDataURL="data:image/png;base64,…" // Tiny placeholder
/>

---

6 — Build Configuration

next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,

  // Enable gzip + brotli compression
  compress: true,

  // Optimise package imports
  experimental: {
    optimizePackageImports: [
      "lucide-react",
      "framer-motion",
    ],
  },

  // Security headers
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          { key: "X-Frame-Options", value: "DENY" },
          { key: "X-Content-Type-Options", value: "nosniff" },
          { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
        ],
      },
    ];
  },
};

export default nextConfig;

TypeScript Strict Mode

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

This catches unused imports and dead code at compile time, preventing bloat from accumulating.

---

7 — Performance Budget

Set targets and measure against them:

| Metric | Target | Tool | | --------------------------- | -------------- | ----------------------- | | First Contentful Paint | < 1.5 s | Lighthouse | | Largest Contentful Paint| < 2.5 s | Lighthouse | | Total Blocking Time | < 200 ms | Lighthouse | | Cumulative Layout Shift | < 0.1 | Lighthouse | | JS Bundle (gzipped) | < 180 kB | next build output | | CSS (gzipped) | < 30 kB | next build output | | Time to Interactive | < 3.0 s (3G) | WebPageTest |

Measuring Bundle Size

# Build and see chunk breakdown
npx next build

# Detailed bundle analysis
ANALYZE=true npx next build
# Requires: npm install @next/bundle-analyzer

next/bundle-analyzer Setup

// next.config.mjs
import withBundleAnalyzer from "@next/bundle-analyzer";

const config = withBundleAnalyzer({
  enabled: process.env.ANALYZE === "true",
})({
  // … your config
});

export default config;

---

8 — Deployment

Vercel (Recommended for Next.js)

# Install Vercel CLI
npm i -g vercel

# Deploy (auto-detects Next.js)
vercel

# Production deploy
vercel --prod

Vercel provides:

• Automatic edge caching for static pages
• ISR support out of the box
• Preview deployments for every PR
• Analytics dashboard

Static Export (Any Host)

If you don't need server-side features:

// next.config.mjs
const nextConfig = {
  output: "export",
  // Images need unoptimized for static export
  images: { unoptimized: true },
};

npx next build
# Output in `out/` — deploy to any static host

Docker

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Requires output: "standalone" in next.config.mjs.

---

9 — Pre-Deploy Checklist

• [ ] npm run build completes without errors
• [ ] Bundle size is within performance budget
• [ ] Lighthouse score ≥ 90 (Performance, Accessibility)
• [ ] Intro animation starts within 1.5 s on throttled 3G
• [ ] All console.log debug statements removed
• [ ] Environment variables set in deployment platform
• [ ] Analytics scripts load with afterInteractive strategy
• [ ] Security headers configured
• [ ] OG meta tags and favicon set in layout metadata
• [ ] robots.txt and sitemap.xml configured
• [ ] 404 page exists and matches the theme

---

Quick Reference: Build Commands

# Development
npm run dev           # Start dev server (Turbopack)

# Production build
npm run build         # Build for production
npm run start         # Start production server locally

# Analysis
ANALYZE=true npm run build   # Bundle size analysis

# Linting
npm run lint          # ESLint check
npx tsc --noEmit      # Type check without build

---

Next: Testing Frontend →