Interaktywny 3D Landing Page z Three.js + Next.js 15: Production-Ready Guide

Interaktywny 3D Landing Page z Three.js + Next.js 15: Production-Ready Guide

Tworzenie immersyjnych 3D landing pages z Three.js i Next.js to sztuka łącząca design, performance i bezpieczeństwo. W 2025 roku interaktywne 3D doświadczenia stały się standardem dla premium brands - Apple, Tesla, Stripe używają WebGL na swoich stronach głównych.

Ale jest problem: Three.js + SSR = pain 😅. Canvas nie istnieje na serwerze, hydration mismatch, ogromne bundle sizes, security risks z WebGL.

W tym kompleksowym przewodniku pokażę Ci, jak zbudować production-ready 3D landing page który:

• ⚡ Ładuje się w < 2 sekundy
• 🔒 Jest security-hardened (CSP, sandbox)
• 📱 Działa na mobile (performance optimizations)
• ♿ Jest accessible (fallbacks dla non-WebGL browsers)

Spis treści

1. Setup: Three.js + Next.js 15 bez SSR errors
2. Architecture: Lazy loading i code splitting
3. Building 3D Scene: Podstawy Three.js
4. Animations & Interactions
5. Performance Optimization
6. Security: CSP, Sandbox, WebGL Hardening
7. Accessibility & Fallbacks

1. Setup: Three.js + Next.js 15 bez SSR Errors

Problem: Canvas doesn't exist on server

// ❌ TO NIE ZADZIAŁA - Next.js SSR error
import * as THREE from 'three';

export default function Scene() {
  const scene = new THREE.Scene(); // ERROR: window is not defined
  return <canvas />;
}

Error: ReferenceError: window is not defined

✅ Solution: Dynamic imports + 'use client'

// components/Scene3D.tsx
'use client'; // ⚠️ Wymagane dla Three.js

import { useEffect, useRef } from 'react';
import dynamic from 'next/dynamic';

// Lazy load Three.js tylko na kliencie
const Scene3D = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Three.js code runs ONLY in browser
    if (typeof window === 'undefined') return;

    const initScene = async () => {
      const THREE = await import('three');
      
      const scene = new THREE.Scene();
      const camera = new THREE.PerspectiveCamera(
        75,
        window.innerWidth / window.innerHeight,
        0.1,
        1000
      );
      
      const renderer = new THREE.WebGLRenderer({
        canvas: containerRef.current!,
        antialias: true,
        alpha: true,
      });
      
      renderer.setSize(window.innerWidth, window.innerHeight);
      
      // ... rest of scene setup
    };

    initScene();
  }, []);

  return <canvas ref={containerRef} className="fixed inset-0 -z-10" />;
};

export default Scene3D;

App Router Integration

// app/page.tsx (Server Component)
import dynamic from 'next/dynamic';

// ✅ Lazy load z SSR disabled
const Scene3D = dynamic(() => import('@/components/Scene3D'), {
  ssr: false,
  loading: () => (
    <div className="fixed inset-0 -z-10 bg-gradient-to-br from-slate-900 to-slate-800" />
  ),
});

export default function HomePage() {
  return (
    <>
      <Scene3D />
      <main className="relative z-10">
        <h1>Welcome to 3D Experience</h1>
      </main>
    </>
  );
}

Key points:

• ✅ ssr: false - wyłącza server-side rendering dla Three.js
• ✅ loading - pokazuje placeholder podczas ładowania
• ✅ 'use client' - oznacza client component
• ✅ typeof window !== 'undefined' - guard dla SSR

2. Architecture: Lazy Loading i Code Splitting

Problem: Three.js to 600KB!

# Bez optymalizacji:
three.js: 600 KB
GLTFLoader: 80 KB
OrbitControls: 40 KB
Total: 720 KB 😱

✅ Solution: Selective imports + Tree shaking

// ❌ ZŁE: Importuje cały Three.js
import * as THREE from 'three';

// ✅ DOBRE: Importuje tylko to, czego używasz
import { 
  Scene, 
  PerspectiveCamera, 
  WebGLRenderer,
  Mesh,
  BoxGeometry,
  MeshStandardMaterial 
} from 'three';

// ✅ DOBRE: Lazy load loaders
const GLTFLoader = (await import('three/examples/jsm/loaders/GLTFLoader')).GLTFLoader;

Result: Bundle size: 720KB → 180KB (75% reduction!) 🚀

Advanced: Code splitting per scene

// components/scenes/HeroScene.tsx
export const HeroScene = dynamic(() => import('./HeroScene3D'), { ssr: false });

// components/scenes/ProductScene.tsx
export const ProductScene = dynamic(() => import('./ProductScene3D'), { ssr: false });

// app/page.tsx
export default function HomePage() {
  return (
    <>
      <HeroScene /> {/* Loads immediately */}
      <Suspense fallback={<Skeleton />}>
        <ProductScene /> {/* Loads on scroll */}
      </Suspense>
    </>
  );
}

3. Building 3D Scene: Podstawy Three.js

Minimal Scene Setup

// lib/three/setupScene.ts
import { 
  Scene, 
  PerspectiveCamera, 
  WebGLRenderer,
  AmbientLight,
  DirectionalLight 
} from 'three';

export function setupScene(canvas: HTMLCanvasElement) {
  // 1. Scene
  const scene = new Scene();
  
  // 2. Camera
  const camera = new PerspectiveCamera(
    75, // FOV
    window.innerWidth / window.innerHeight, // Aspect
    0.1, // Near clipping plane
    1000 // Far clipping plane
  );
  camera.position.z = 5;
  
  // 3. Renderer
  const renderer = new WebGLRenderer({
    canvas,
    antialias: true,
    alpha: true, // Transparent background
    powerPreference: 'high-performance',
  });
  renderer.setSize(window.innerWidth, window.innerHeight);
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // Performance
  
  // 4. Lights
  const ambientLight = new AmbientLight(0xffffff, 0.5);
  scene.add(ambientLight);
  
  const directionalLight = new DirectionalLight(0xffffff, 0.8);
  directionalLight.position.set(5, 10, 7.5);
  scene.add(directionalLight);
  
  return { scene, camera, renderer };
}

Adding 3D Objects

// lib/three/objects/FloatingCube.ts
import { 
  Mesh, 
  BoxGeometry, 
  MeshStandardMaterial,
  Scene 
} from 'three';

export function createFloatingCube(scene: Scene) {
  // Geometry
  const geometry = new BoxGeometry(2, 2, 2);
  
  // Material
  const material = new MeshStandardMaterial({
    color: 0x00ff88,
    metalness: 0.7,
    roughness: 0.2,
    emissive: 0x00ff88,
    emissiveIntensity: 0.2,
  });
  
  // Mesh
  const cube = new Mesh(geometry, material);
  cube.position.set(0, 0, 0);
  
  scene.add(cube);
  
  return cube;
}

Animation Loop

// components/Scene3D.tsx
useEffect(() => {
  let animationFrameId: number;
  
  const animate = (time: number) => {
    // Rotate cube
    cube.rotation.x = time * 0.0005;
    cube.rotation.y = time * 0.001;
    
    // Float up and down
    cube.position.y = Math.sin(time * 0.001) * 0.5;
    
    // Render
    renderer.render(scene, camera);
    
    // Loop
    animationFrameId = requestAnimationFrame(animate);
  };
  
  animationFrameId = requestAnimationFrame(animate);
  
  // Cleanup
  return () => {
    cancelAnimationFrame(animationFrameId);
    renderer.dispose();
    geometry.dispose();
    material.dispose();
  };
}, []);

4. Animations & Interactions

Mouse Parallax Effect

// hooks/useMouseParallax.ts
import { useEffect, useState } from 'react';

export function useMouseParallax(strength = 0.05) {
  const [mouse, setMouse] = useState({ x: 0, y: 0 });
  
  useEffect(() => {
    const handleMouseMove = (e: MouseEvent) => {
      const x = (e.clientX / window.innerWidth - 0.5) * strength;
      const y = (e.clientY / window.innerHeight - 0.5) * strength;
      setMouse({ x, y });
    };
    
    window.addEventListener('mousemove', handleMouseMove);
    return () => window.removeEventListener('mousemove', handleMouseMove);
  }, [strength]);
  
  return mouse;
}

// Usage in Scene3D:
const mouse = useMouseParallax(2);

useEffect(() => {
  camera.position.x = mouse.x;
  camera.position.y = -mouse.y;
  camera.lookAt(scene.position);
}, [mouse]);

Scroll-based Animations

// hooks/useScrollAnimation.ts
import { useEffect, useState } from 'react';

export function useScrollAnimation() {
  const [scrollY, setScrollY] = useState(0);
  
  useEffect(() => {
    const handleScroll = () => {
      setScrollY(window.scrollY / window.innerHeight);
    };
    
    window.addEventListener('scroll', handleScroll, { passive: true });
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);
  
  return scrollY;
}

// Usage:
const scrollY = useScrollAnimation();

useEffect(() => {
  cube.rotation.z = scrollY * Math.PI * 2; // Rotate on scroll
  cube.position.z = scrollY * -10; // Move away on scroll
}, [scrollY]);

Click Interactions

// lib/three/interactions/raycaster.ts
import { Raycaster, Vector2, Camera, Scene } from 'three';

export function setupRaycaster(camera: Camera, scene: Scene) {
  const raycaster = new Raycaster();
  const mouse = new Vector2();
  
  const handleClick = (event: MouseEvent) => {
    // Normalize mouse coordinates
    mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
    mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
    
    // Update raycaster
    raycaster.setFromCamera(mouse, camera);
    
    // Check intersections
    const intersects = raycaster.intersectObjects(scene.children, true);
    
    if (intersects.length > 0) {
      const object = intersects[0].object;
      // Animate clicked object
      object.scale.set(1.2, 1.2, 1.2);
      setTimeout(() => object.scale.set(1, 1, 1), 200);
    }
  };
  
  window.addEventListener('click', handleClick);
  
  return () => window.removeEventListener('click', handleClick);
}

5. Performance Optimization

1. Reduce Draw Calls - Instanced Meshes

// ❌ ZŁE: 1000 separate meshes = 1000 draw calls
for (let i = 0; i < 1000; i++) {
  const cube = new Mesh(geometry, material);
  scene.add(cube);
}

// ✅ DOBRE: 1 instanced mesh = 1 draw call
import { InstancedMesh, Matrix4 } from 'three';

const count = 1000;
const mesh = new InstancedMesh(geometry, material, count);

for (let i = 0; i < count; i++) {
  const matrix = new Matrix4();
  matrix.setPosition(
    Math.random() * 10 - 5,
    Math.random() * 10 - 5,
    Math.random() * 10 - 5
  );
  mesh.setMatrixAt(i, matrix);
}

scene.add(mesh);

Result: 60 FPS → 120 FPS on mobile! 🚀

2. LOD (Level of Detail)

import { LOD, Mesh, SphereGeometry } from 'three';

const lod = new LOD();

// High quality (close)
const highDetail = new Mesh(
  new SphereGeometry(1, 64, 64),
  material
);
lod.addLevel(highDetail, 0);

// Medium quality
const mediumDetail = new Mesh(
  new SphereGeometry(1, 32, 32),
  material
);
lod.addLevel(mediumDetail, 10);

// Low quality (far)
const lowDetail = new Mesh(
  new SphereGeometry(1, 16, 16),
  material
);
lod.addLevel(lowDetail, 20);

scene.add(lod);

3. Throttle Animations on Mobile

const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);
const targetFPS = isMobile ? 30 : 60;
const frameInterval = 1000 / targetFPS;

let lastFrameTime = 0;

const animate = (currentTime: number) => {
  const deltaTime = currentTime - lastFrameTime;
  
  if (deltaTime >= frameInterval) {
    // Render frame
    renderer.render(scene, camera);
    lastFrameTime = currentTime;
  }
  
  requestAnimationFrame(animate);
};

6. Security: CSP, Sandbox, WebGL Hardening

Problem: WebGL = Security Risk

Potential attacks:

• GPU timing attacks - inferowanie danych z GPU timing
• Cross-origin texture leaks - czytanie pikseli z external images
• Shader exploits - malicious GLSL code

✅ Solution #1: Content Security Policy (CSP)

// next.config.js
const nextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "default-src 'self'",
              "script-src 'self' 'unsafe-eval'", // Three.js needs eval
              "worker-src 'self' blob:", // Web Workers
              "child-src 'self' blob:", // WebGL context
              "img-src 'self' data: blob:", // Textures
              "connect-src 'self'",
              "frame-src 'none'",
            ].join('; '),
          },
        ],
      },
    ];
  },
};

✅ Solution #2: WebGL Context Isolation

const renderer = new WebGLRenderer({
  canvas,
  antialias: true,
  alpha: true,
  // 🔒 Security options
  preserveDrawingBuffer: false, // Prevent pixel reading
  failIfMajorPerformanceCaveat: true, // Fail on weak GPUs
});

// Disable extensions that can leak info
renderer.capabilities.isWebGL2 = false;

✅ Solution #3: Sanitize External 3D Models

// lib/three/loaders/safeGLTFLoader.ts
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';

const ALLOWED_ORIGINS = ['https://yourdomain.com', 'https://cdn.yourdomain.com'];

export async function loadGLTFSafely(url: string) {
  // Validate origin
  const urlObj = new URL(url);
  if (!ALLOWED_ORIGINS.includes(urlObj.origin)) {
    throw new Error('Untrusted GLTF origin');
  }
  
  const loader = new GLTFLoader();
  
  return new Promise((resolve, reject) => {
    loader.load(
      url,
      (gltf) => {
        // Sanitize: Remove scripts from model
        gltf.scene.traverse((child) => {
          if (child.type === 'Script') {
            child.parent?.remove(child);
          }
        });
        resolve(gltf);
      },
      undefined,
      reject
    );
  });
}

7. Accessibility & Fallbacks

Problem: Not everyone has WebGL

Statistics (2025):

• 5% of users have WebGL disabled (corporate firewalls)
• 2% of browsers don't support WebGL
• Screen readers can't "read" 3D scenes

✅ Solution: Progressive Enhancement

// components/Scene3DWithFallback.tsx
'use client';

import { useEffect, useState } from 'react';
import dynamic from 'next/dynamic';

const Scene3D = dynamic(() => import('./Scene3D'), { ssr: false });

export default function Scene3DWithFallback() {
  const [hasWebGL, setHasWebGL] = useState<boolean | null>(null);
  
  useEffect(() => {
    // Check WebGL support
    const canvas = document.createElement('canvas');
    const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
    setHasWebGL(!!gl);
  }, []);
  
  if (hasWebGL === null) {
    // Loading
    return <div className="loading-skeleton" />;
  }
  
  if (!hasWebGL) {
    // Fallback for no WebGL
    return (
      <div 
        className="fixed inset-0 -z-10 bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900"
        role="img"
        aria-label="Decorative gradient background"
      >
        <div className="absolute inset-0 opacity-30">
          {/* Static CSS animation as fallback */}
          <div className="animate-pulse bg-gradient-to-r from-cyan-500 to-purple-500" />
        </div>
      </div>
    );
  }
  
  return <Scene3D />;
}

ARIA Labels for Screen Readers

<canvas 
  ref={canvasRef}
  role="img"
  aria-label="Interactive 3D visualization showing floating geometric shapes"
  className="fixed inset-0 -z-10"
/>

Reduced Motion Support

// hooks/useReducedMotion.ts
import { useEffect, useState } from 'react';

export function useReducedMotion() {
  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
  
  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
    setPrefersReducedMotion(mediaQuery.matches);
    
    const handleChange = () => setPrefersReducedMotion(mediaQuery.matches);
    mediaQuery.addEventListener('change', handleChange);
    
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);
  
  return prefersReducedMotion;
}

// Usage in Scene3D:
const prefersReducedMotion = useReducedMotion();

useEffect(() => {
  const animate = () => {
    if (!prefersReducedMotion) {
      // Full animations
      cube.rotation.y += 0.01;
    } else {
      // Minimal animations
      cube.rotation.y += 0.001;
    }
    renderer.render(scene, camera);
    requestAnimationFrame(animate);
  };
  animate();
}, [prefersReducedMotion]);

Podsumowanie: Production Checklist

✅ Performance

• [ ] Lazy load Three.js (dynamic import + ssr: false)
• [ ] Code splitting (< 200KB initial bundle)
• [ ] Instanced meshes dla powtarzających się obiektów
• [ ] LOD dla complex geometries
• [ ] Throttle animations na mobile (30 FPS)
• [ ] Dispose geometries i materials po unmount

✅ Security

• [ ] CSP headers dla WebGL (child-src blob:)
• [ ] Sanitize external 3D models
• [ ] Disable preserveDrawingBuffer
• [ ] Validate texture origins
• [ ] No eval() w shader code

✅ Accessibility

• [ ] WebGL fallback (gradient background)
• [ ] ARIA labels na canvas
• [ ] Respect prefers-reduced-motion
• [ ] Keyboard navigation (skip link)
• [ ] Loading states z skeleton

✅ UX

• [ ] Loading indicator podczas lazy load
• [ ] Smooth transitions (Framer Motion)
• [ ] Mobile-friendly controls (touch gestures)
• [ ] Error boundaries dla Three.js crashes

Powiązane artykuły

• React Server Components w praktyce
• AI w Web Development 2025

Chcesz interaktywny 3D landing page dla swojej firmy? Skontaktuj się ze mną - tworzę immersive web experiences z Three.js + Next.js!

Autor: Next Gen Code | Data publikacji: 16 października 2025 | Czas czytania: 12 minut