Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje
Monorepo z Turborepo - Skalowanie projektów Next.js
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-devStruktura 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.jsonKonfiguracja 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 pakietoutputs- co cachować (foldery wynikowe)cache: false- dev server nie powinien być cachowanypersistent: 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.3sRemote Caching z Vercel
# Połącz z Vercel Remote Cache
npx turbo login
npx turbo link
# Teraz cache jest współdzielony między developerami i CIFiltrowanie 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/admin2. 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:
- Współdzielone pakiety - UI, typy, konfiguracje używane w wielu aplikacjach
- Inteligentny cache - pomijanie niezmienionych pakietów, przyspieszenie buildów
- Pipeline - zależności między zadaniami, równoległe budowanie
- Workspace dependencies -
workspace:*dla wewnętrznych pakietów - Remote caching - współdzielony cache między developerami i CI
- 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. 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)