Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje

Monorepo z Turborepo - Skalowanie projektów Next.js

5 min czytania ·
W tej lekcji8

W rozległej infrastrukturze Metropolii Quantum 2150, gdzie dziesiątki mikroserwisów i aplikacji frontendowych współpracują ze sobą, potrzebujesz narzędzia do zarządzania kodem na wielką skalę. Turborepo to system budowania dla monorepo, który działa z Next.js jak precyzyjny kwantowy procesor - szybko, wydajnie i niezawodnie.

Dlaczego monorepo dla Next.js?

Monorepo to strategia przechowywania wielu projektów w jednym repozytorium. Dla ekosystemu Next.js daje to ogromne korzyści:

  • Współdzielenie kodu - komponenty UI, konfiguracje, typy używane w wielu aplikacjach
  • Atomowe zmiany - zmiana w współdzielonej bibliotece natychmiast widoczna wszędzie
  • Spójny tooling - jedna konfiguracja ESLint, TypeScript, Prettier
  • Uproszczone CI/CD - jeden pipeline dla całego ekosystemu
  • Lepsza współpraca - wszystko w jednym miejscu, łatwy code review

Konfiguracja Turborepo

Inicjalizacja monorepo

# Utwórz nowe monorepo z Turborepo
npx create-turbo@latest quantum-monorepo

# Lub dodaj Turborepo do istniejącego projektu
npm install turbo --save-dev

Struktura katalogów

quantum-monorepo/
  apps/
    web/                 # Główna aplikacja Next.js
      package.json
      next.config.js
    admin/               # Panel admina Next.js
      package.json
      next.config.js
    docs/                # Dokumentacja Next.js
      package.json

  packages/
    ui/                  # Współdzielone komponenty React
      package.json
      src/
        Button.tsx
        Card.tsx
        index.ts
    config-eslint/       # Współdzielona konfiguracja ESLint
      package.json
    config-typescript/   # Współdzielona konfiguracja TypeScript
      package.json
    types/               # Współdzielone interfejsy TypeScript
      package.json
      src/
        user.ts
        product.ts

  turbo.json             # Konfiguracja Turborepo
  package.json           # Root package.json

Konfiguracja turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["^build"]
    },
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

Kluczowe elementy konfiguracji:

  • dependsOn: ["^build"] - buduj zależności zanim zbudujesz pakiet
  • outputs - co cachować (foldery wynikowe)
  • cache: false - dev server nie powinien być cachowany
  • persistent: true - procesy długotrwałe (dev server)

Root package.json

{
  "name": "quantum-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "type-check": "turbo type-check"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

Współdzielone pakiety

Pakiet UI - komponenty React

// packages/ui/package.json
{
  "name": "@quantum/ui",
  "version": "0.1.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "dependencies": {
    "react": "^19.2.0"
  },
  "devDependencies": {
    "@quantum/config-typescript": "workspace:*",
    "typescript": "^5.5.0"
  }
}
// packages/ui/src/Button.tsx
import React from 'react';

interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'danger';
  onClick?: () => void;
  disabled?: boolean;
}

export function Button({ children, variant = 'primary', onClick, disabled }: ButtonProps) {
  const styles = {
    primary: { background: '#7c4dff', color: '#fff' },
    secondary: { background: '#64ffda', color: '#000' },
    danger: { background: '#f44336', color: '#fff' },
  };

  return (
    <button
      onClick={onClick}
      disabled={disabled}
      style={{
        ...styles[variant],
        padding: '10px 24px',
        borderRadius: '8px',
        border: 'none',
        cursor: disabled ? 'not-allowed' : 'pointer',
        opacity: disabled ? 0.5 : 1,
      }}
    >
      {children}
    </button>
  );
}
// packages/ui/src/index.ts
export { Button } from './Button';
export { Card } from './Card';

Pakiet types - współdzielone interfejsy

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user' | 'moderator';
  createdAt: string;
}
// packages/types/src/index.ts
export * from './user';
export * from './product';

Workspace dependencies

Aby użyć współdzielonego pakietu w aplikacji Next.js:

// apps/web/package.json
{
  "name": "@quantum/web",
  "dependencies": {
    "@quantum/ui": "workspace:*",
    "@quantum/types": "workspace:*",
    "next": "^16.0.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@quantum/config-typescript": "workspace:*",
    "@quantum/config-eslint": "workspace:*"
  }
}

Użycie w kodzie aplikacji:

// apps/web/app/page.tsx
import { Button, Card } from '@quantum/ui';
import type { Product } from '@quantum/types';

export default async function HomePage() {
  return (
    <div>
      <h1>Quantum Store</h1>
      <Button variant="primary">Dodaj do koszyka</Button>
    </div>
  );
}

Cache i pipeline Turborepo

Turborepo używa inteligentnego systemu cache, który zapamiętuje wyniki budowania i pomija niezmienione pakiety.

Jak działa cache

# Pierwsze budowanie - wszystko od zera
npx turbo build
# Output: 5 tasks, 0 cached, 5 not cached
# Czas: 45s

# Drugie budowanie (bez zmian) - pełny cache
npx turbo build
# Output: 5 tasks, 5 cached, 0 not cached
# Czas: 0.3s

Remote Caching z Vercel

# Połącz z Vercel Remote Cache
npx turbo login
npx turbo link

# Teraz cache jest współdzielony między developerami i CI

Filtrowanie budowania

# Zbuduj tylko konkretną aplikację
npx turbo build --filter=@quantum/web

# Zbuduj aplikację i jej zależności
npx turbo build --filter=@quantum/web...

# Zbuduj tylko to co się zmieniło od ostatniego commita
npx turbo build --filter=[HEAD^1]

Deploying z monorepo na Vercel

Konfiguracja next.config.js dla monorepo

// apps/web/next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@quantum/ui'],
  output: 'standalone',
};

module.exports = nextConfig;

Opcja transpilePackages mówi Next.js, żeby transpilować kod z pakietów monorepo (domyślnie Next.js nie transpiluje node_modules).

Wieloaplikacyjny deploy

Vercel automatycznie buduje tylko zmienione aplikacje. Jeśli zmienisz packages/ui, aplikacje zależne od tego pakietu zostaną przebudowane, a te niezależne - pominięte.

Najlepsze praktyki

1. Konwencje nazewnictwa pakietów

Używaj scope (@nazwa-organizacji/) dla wszystkich pakietów i aplikacji:

@quantum/ui
@quantum/types
@quantum/config-eslint
@quantum/web
@quantum/admin

2. Wersjonowanie

Używaj workspace:* dla wewnętrznych zależności - nigdy nie hardcoduj wersji:

"@quantum/ui": "workspace:*"

3. Zarządzanie zmiennymi środowiskowymi

Każda aplikacja ma własny plik .env, a turbo.json deklaruje globalne zależności od plików środowiskowych.

Podsumowanie

Turborepo to potężne narzędzie do skalowania projektów Next.js w architekturze monorepo:

  1. Współdzielone pakiety - UI, typy, konfiguracje używane w wielu aplikacjach
  2. Inteligentny cache - pomijanie niezmienionych pakietów, przyspieszenie buildów
  3. Pipeline - zależności między zadaniami, równoległe budowanie
  4. Workspace dependencies - workspace:* dla wewnętrznych pakietów
  5. Remote caching - współdzielony cache między developerami i CI
  6. Deploy na Vercel - natywne wsparcie, automatyczne wykrywanie zmian

W Metropolii Quantum 2150, gdzie każdy projekt rośnie i wymaga skalowania, Turborepo jest fundamentem architektury - pozwala zarządzać dziesiątkami aplikacji i bibliotek z jednego miejsca.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

interface Package {
  name: string;
  type: 'app' | 'package';
  status: 'cached' | 'building' | 'built' | 'pending';
  duration?: number;
  deps: string[];
}

const TurborepoDemo = () => {
  const [packages, setPackages] = useState<Package[]>([
    { name: '@quantum/web', type: 'app', status: 'pending', deps: ['@quantum/ui', '@quantum/types'] },
    { name: '@quantum/admin', type: 'app', status: 'pending', deps: ['@quantum/ui', '@quantum/types'] },
    { name: '@quantum/docs', type: 'app', status: 'pending', deps: [] },
    { name: '@quantum/ui', type: 'package', status: 'pending', deps: ['@quantum/types'] },
    { name: '@quantum/types', type: 'package', status: 'pending', deps: [] },
    { name: '@quantum/config-ts', type: 'package', status: 'pending', deps: [] },
    { name: '@quantum/config-eslint', type: 'package', status: 'pending', deps: [] },
  ]);
  const [running, setRunning] = useState(false);
  const [logs, setLogs] = useState<string[]>([]);
  const [cacheEnabled, setCacheEnabled] = useState(true);
  const [buildCount, setBuildCount] = useState(0);
  const [changedPkg, setChangedPkg] = useState<string | null>(null);

  const addLog = (msg: string) => setLogs(prev => [...prev.slice(-12), msg]);
  const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));

  const statusIcon = (s: string) => {
    switch (s) {
      case 'built': case 'cached': return '✅';
      case 'building': return '⏳';
      default: return '⚪';
    }
  };

  const statusColor = (s: string) => {
    switch (s) {
      case 'built': return '#4caf50';
      case 'cached': return '#64ffda';
      case 'building': return '#ff9800';
      default: return '#555';
    }
  };

  const runBuild = async () => {
    setRunning(true);
    setLogs([]);
    setPackages(prev => prev.map(p => ({ ...p, status: 'pending', duration: undefined })));
    setBuildCount(c => c + 1);
    const isSecondBuild = buildCount > 0;

    addLog('$ npx turbo build' + (changedPkg ? ' --filter=' + changedPkg + '...' : ''));

    // Build packages first (no deps first)
    const noDeps = packages.filter(p => p.type === 'package' && p.deps.length === 0);
    for (const pkg of noDeps) {
      const isCached = isSecondBuild && cacheEnabled && pkg.name !== changedPkg;
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: 'building' } : p));
      addLog((isCached ? 'CACHE HIT ' : 'Building ') + pkg.name);
      await sleep(isCached ? 100 : 300);
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: isCached ? 'cached' : 'built', duration: isCached ? 0 : 2 } : p));
    }

    // Then packages with deps
    const withDeps = packages.filter(p => p.type === 'package' && p.deps.length > 0);
    for (const pkg of withDeps) {
      const isCached = isSecondBuild && cacheEnabled && pkg.name !== changedPkg && !pkg.deps.includes(changedPkg || '');
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: 'building' } : p));
      addLog((isCached ? 'CACHE HIT ' : 'Building ') + pkg.name);
      await sleep(isCached ? 100 : 400);
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: isCached ? 'cached' : 'built', duration: isCached ? 0 : 5 } : p));
    }

    // Then apps
    const apps = packages.filter(p => p.type === 'app');
    for (const pkg of apps) {
      const affectedByChange = changedPkg && (pkg.deps.includes(changedPkg) || pkg.name === changedPkg);
      const isCached = isSecondBuild && cacheEnabled && !affectedByChange;
      if (changedPkg && !affectedByChange && pkg.name !== changedPkg) {
        setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: 'cached', duration: 0 } : p));
        addLog('SKIP ' + pkg.name + ' (not affected)');
        await sleep(80);
        continue;
      }
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: 'building' } : p));
      addLog((isCached ? 'CACHE HIT ' : 'Building ') + pkg.name);
      await sleep(isCached ? 150 : 600);
      setPackages(prev => prev.map(p => p.name === pkg.name ? { ...p, status: isCached ? 'cached' : 'built', duration: isCached ? 0 : 15 } : p));
    }

    const cached = packages.filter(() => true).length; // placeholder
    addLog('Build complete!');
    setRunning(false);
    setChangedPkg(null);
  };

  const simulateChange = (pkgName: string) => {
    setChangedPkg(pkgName);
    addLog('Changed: ' + pkgName);
  };

  const reset = () => {
    setPackages(prev => prev.map(p => ({ ...p, status: 'pending', duration: undefined })));
    setLogs([]);
    setBuildCount(0);
    setChangedPkg(null);
  };

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: '20px', color: '#fff', fontFamily: 'sans-serif' }}>
      <h1 style={{ color: '#64ffda', textAlign: 'center' }}>Monorepo z Turborepo</h1>
      <p style={{ textAlign: 'center', color: '#888', marginBottom: '20px' }}>Shared packages + Intelligent caching + Pipeline</p>

      <div style={{ maxWidth: '900px', margin: '0 auto' }}>
        <div style={{ display: 'flex', gap: '8px', justifyContent: 'center', marginBottom: '16px', flexWrap: 'wrap' }}>
          <button onClick={runBuild} disabled={running}
            style={{ padding: '8px 20px', background: running ? '#555' : '#4caf50', border: 'none', borderRadius: '6px', color: '#fff', cursor: running ? 'default' : 'pointer', fontWeight: 'bold' }}>
            {running ? 'Building...' : 'turbo build'}
          </button>
          <button onClick={reset} disabled={running}
            style={{ padding: '8px 20px', background: 'rgba(255,255,255,0.1)', border: 'none', borderRadius: '6px', color: '#fff', cursor: 'pointer' }}>
            Reset
          </button>
          <label style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
            <input type="checkbox" checked={cacheEnabled} onChange={() => setCacheEnabled(!cacheEnabled)} />
            <span style={{ color: cacheEnabled ? '#64ffda' : '#666', fontSize: '13px' }}>Remote Cache</span>
          </label>
        </div>

        {buildCount > 0 && !running && (
          <div style={{ display: 'flex', gap: '6px', justifyContent: 'center', marginBottom: '12px', flexWrap: 'wrap' }}>
            <span style={{ color: '#888', fontSize: '12px', padding: '4px 0' }}>Simulate change in:</span>
            {packages.filter(p => p.type === 'package').map(p => (
              <button key={p.name} onClick={() => simulateChange(p.name)}
                style={{ padding: '4px 10px', background: changedPkg === p.name ? '#ff9800' : 'rgba(255,255,255,0.1)', border: 'none', borderRadius: '4px', color: '#fff', cursor: 'pointer', fontSize: '11px' }}>
                {p.name.replace('@quantum/', '')}
              </button>
            ))}
          </div>
        )}

        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px' }}>
          <div>
            <h3 style={{ color: '#7c4dff', marginBottom: '10px' }}>Workspace Packages</h3>
            <div style={{ background: 'rgba(255,255,255,0.05)', borderRadius: '10px', overflow: 'hidden' }}>
              {packages.map(pkg => (
                <div key={pkg.name} style={{ display: 'flex', alignItems: 'center', gap: '8px', padding: '10px 12px', borderBottom: '1px solid #1a1a2e' }}>
                  <span>{statusIcon(pkg.status)}</span>
                  <span style={{ background: pkg.type === 'app' ? '#7c4dff33' : '#64ffda33', color: pkg.type === 'app' ? '#7c4dff' : '#64ffda', padding: '2px 6px', borderRadius: '4px', fontSize: '10px' }}>
                    {pkg.type}
                  </span>
                  <span style={{ flex: 1, color: statusColor(pkg.status), fontSize: '13px' }}>{pkg.name}</span>
                  {pkg.status === 'cached' && <span style={{ color: '#64ffda', fontSize: '10px' }}>CACHED</span>}
                  {pkg.duration !== undefined && pkg.duration > 0 && <span style={{ color: '#555', fontSize: '11px' }}>{pkg.duration}s</span>}
                </div>
              ))}
            </div>

            <div style={{ marginTop: '12px', background: 'rgba(255,255,255,0.05)', padding: '12px', borderRadius: '8px' }}>
              <h4 style={{ color: '#64ffda', fontSize: '12px', marginBottom: '8px' }}>Dependency Graph</h4>
              <div style={{ fontSize: '11px', fontFamily: 'monospace', color: '#888' }}>
                <div>@quantum/web ── @quantum/ui ── @quantum/types</div>
                <div>@quantum/admin ── @quantum/ui ── @quantum/types</div>
                <div>@quantum/docs (no internal deps)</div>
              </div>
            </div>
          </div>

          <div>
            <h3 style={{ color: '#7c4dff', marginBottom: '10px' }}>Build Log</h3>
            <div style={{ background: '#000', padding: '12px', borderRadius: '8px', minHeight: '300px', maxHeight: '400px', overflowY: 'auto', fontFamily: 'monospace', fontSize: '11px' }}>
              {logs.length === 0 ? (
                <span style={{ color: '#555' }}>Click "turbo build" to start...</span>
              ) : logs.map((log, i) => (
                <div key={i} style={{ color: log.includes('CACHE') ? '#64ffda' : log.includes('SKIP') ? '#888' : log.includes('Building') ? '#ff9800' : '#0f0', padding: '2px 0' }}>
                  {log}
                </div>
              ))}
            </div>
          </div>
        </div>
      </div>
    </div>
  );
};

export default TurborepoDemo;

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Które stwierdzenie najlepiej opisuje główną zaletę Turborepo w projektach Next.js?

Zadania praktyczne w grze

  • Układanie w pionie

    Ułóż kolejność budowania pakietów w monorepo Turborepo (od pakietów bez zależności do aplikacji)

  1. PytanieTurborepo - zarządzanie monorepo
  2. Ułóż w kolejnościPipeline budowania w Turborepo

Przydatne artykuły