Instalacja i konfiguracja środowiska programistycznego

W Metropolii Quantum, zanim inżynier może rozpocząć pracę nad systemami miasta, musi przygotować swoje biometryczne stanowisko kwantowe. Podobnie, jako programista Next.js, musisz najpierw skonfigurować swoje środowisko deweloperskie. W tym module nauczysz się, jak zainstalować i skonfigurować wszystkie niezbędne narzędzia do tworzenia aplikacji w Next.js 16.

Wymagania systemowe

Zanim rozpoczniemy instalację, upewnij się, że Twój komputer spełnia minimalne wymagania. Podobnie jak kwantowe terminale w Metropolii Quantum wymagają określonych specyfikacji energetycznych, tak środowisko Next.js potrzebuje odpowiednich wersji oprogramowania:

• Node.js - wersja 20.9 lub nowsza (Next.js 16 nie obsługuje już Node.js 18; najlepiej wybierz aktualną wersję LTS)
• TypeScript (opcjonalnie) - wersja 5.1 lub nowsza
• macOS, Windows (w tym WSL) lub Linux
• Minimum 1GB RAM (zalecane 4GB lub więcej dla większych projektów)
• Edytor kodu - zalecane Visual Studio Code z rozszerzeniami dla React/Next.js

Instalacja Node.js i npm

Node.js to jak generator energii kwantowej dla Twojego środowiska deweloperskiego - zasila wszystkie procesy i narzędzia.

Windows i macOS

1. Odwiedź oficjalną stronę Node.js
2. Pobierz i zainstaluj najnowszą wersję LTS (Long Term Support)
3. Sprawdź instalację, otwierając terminal i wpisując:

1node -v
2npm -v

Powinieneś zobaczyć numery wersji Node.js i npm (Node Package Manager).

Linux (Ubuntu/Debian)

1# Repozytoria Ubuntu 22.04/24.04 i Debiana 12 mają za stary Node.js (12 lub 18),
2# a Next.js 16 wymaga wersji 20.9 lub nowszej. Zainstaluj aktualne LTS z NodeSource:
3curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
4sudo apt install nodejs

Zarządzanie wersjami Node.js

Dla bardziej zaawansowanych użytkowników, podobnie jak inżynierowie Metropolii Quantum używają systemów wirtualizacji do testowania różnych konfiguracji energetycznych, możesz użyć narzędzi do zarządzania wersjami Node.js:

• nvm (Node Version Manager) dla macOS/Linux
• nvm-windows dla Windows

1# Instalacja nvm (macOS/Linux)
2curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
3
4# Instalacja określonej wersji Node.js
5nvm install 24
6nvm use 24

Instalacja edytora kodu

W Metropolii Quantum holograficzne edytory kodu są zintegrowane z neuronowymi implantami inżynierów. Na szczęście w naszym świecie wystarczy zainstalować dobry edytor kodu na komputerze. Visual Studio Code to obecnie jeden z najpopularniejszych edytorów dla programistów Next.js.

1. Pobierz i zainstaluj Visual Studio Code
2. Zainstaluj przydatne rozszerzenia:
   • ES7+ React/Redux/React-Native snippets - szablony kodu
   • ESLint - analiza statyczna kodu
   • Prettier - formatowanie kodu
   • Tailwind CSS IntelliSense (jeśli planujesz używać Tailwind CSS)
   • GitHub Copilot (opcjonalnie) - asystent AI dla programistów

Tworzenie nowego projektu Next.js

Teraz, gdy masz już zainstalowane niezbędne narzędzia, możesz stworzyć swój pierwszy projekt Next.js 16. Vercel udostępnia wygodne narzędzie create-next-app, które automatycznie konfiguruje projekt z najlepszymi praktykami.

1npx create-next-app@latest my-quantum-app

Podczas instalacji zostaniesz poproszony o odpowiedź na kilka pytań konfiguracyjnych:

1Would you like to use the recommended Next.js defaults? No, customize settings
2Would you like to use TypeScript? Yes
3Which linter would you like to use? ESLint
4Would you like to use React Compiler? No
5Would you like to use Tailwind CSS? Yes
6Would you like your code inside a `src/` directory? Yes
7Would you like to use App Router? (recommended) Yes
8Would you like to customize the import alias (`@/*` by default)? No
9Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? Yes

W Next.js 16 kreator zaczyna od pytania o zalecane ustawienia domyślne: odpowiedź "Yes, use recommended defaults" od razu wybiera TypeScript, ESLint, Tailwind CSS, App Router i plik AGENTS.md. Wybieramy "No, customize settings", bo chcemy dodatkowo umieścić kod w katalogu src/. React Compiler, który automatycznie memoizuje komponenty, na razie zostawiamy wyłączony, a AGENTS.md to plik z instrukcjami dla asystentów AI, wskazujący im dokumentację zgodną z zainstalowaną wersją Next.js.

Zalecamy odpowiedź "Yes" na większość pytań, zwłaszcza dotyczących TypeScript i App Router, które są kluczowe dla nowoczesnych aplikacji Next.js 16.

Po zakończeniu instalacji przejdź do katalogu projektu i uruchom serwer deweloperski:

1cd my-quantum-app
2npm run dev

Twoja aplikacja powinna być teraz dostępna pod adresem http://localhost:3000.

Alternatywne metody instalacji

Yarn

Jeśli wolisz używać Yarn zamiast npm:

1npm install -g yarn
2yarn create next-app my-quantum-app

pnpm

pnpm to alternatywny menedżer pakietów, który może zaoszczędzić miejsce na dysku:

1npm install -g pnpm
2pnpm create next-app my-quantum-app

Konfiguracja TypeScript

TypeScript to jak system bezpieczeństwa w Metropolii Quantum - zapobiega błędom przed ich wystąpieniem. Next.js ma wbudowane wsparcie dla TypeScript, a najnowsze wersje create-next-app skonfigurują go automatycznie. Jeśli tworzysz projekt ręcznie, możesz dodać TypeScript później:

1touch tsconfig.json
2npm run dev

Next.js wykryje plik tsconfig.json, sam zainstaluje brakujące zależności (typescript, @types/react, @types/node) i uzupełni plik zalecaną konfiguracją.

Struktura projektu Next.js 16 z App Routerem

Po utworzeniu nowego projektu zobaczysz następującą strukturę katalogów:

1my-quantum-app/
2├── node_modules/      # Zainstalowane zależności
3├── public/            # Statyczne pliki (obrazy, czcionki)
4├── src/               # Kod źródłowy aplikacji
5│   ├── app/           # Katalog App Router
6│   │   ├── layout.tsx # Główny układ
7│   │   ├── page.tsx   # Strona główna
8│   │   └── globals.css # Style globalne (tu konfigurujesz też Tailwind CSS 4)
9├── AGENTS.md          # Wskazówki dla asystentów AI
10├── CLAUDE.md          # Odsyła do AGENTS.md
11├── eslint.config.mjs  # Konfiguracja ESLint (format flat config)
12├── next-env.d.ts      # Typy Next.js dla TypeScript
13├── next.config.ts     # Konfiguracja Next.js
14├── package.json       # Zależności i skrypty
15├── postcss.config.mjs # Konfiguracja PostCSS (wtyczka Tailwind CSS)
16└── tsconfig.json      # Konfiguracja TypeScript

W porównaniu ze starszymi wersjami zniknął plik tailwind.config.js: Tailwind CSS 4, który instaluje create-next-app, konfigurujesz bezpośrednio w globals.css. ESLint korzysta z nowego formatu eslint.config.mjs, a konfiguracja Next.js powstaje od razu w TypeScript jako next.config.ts.

Konfiguracja ESLint

ESLint to jak system monitorowania jakości powietrza w Metropolii Quantum - dba o czystość i jakość kodu. create-next-app tworzy podstawową konfigurację ESLint w pliku eslint.config.mjs (format flat config), a skrypt npm run lint uruchamia po prostu polecenie eslint. Next.js 16 usunął dawne polecenie next lint i nie sprawdza już kodu podczas next build, więc lintera uruchamiasz sam. Konfigurację możesz rozszerzyć, np. o Prettiera:

1npm install --save-dev eslint-config-prettier eslint-plugin-prettier

Następnie zaktualizuj plik eslint.config.mjs:

1// eslint.config.mjs
2import { defineConfig, globalIgnores } from 'eslint/config';
3import nextVitals from 'eslint-config-next/core-web-vitals';
4import nextTs from 'eslint-config-next/typescript';
5import prettierRecommended from 'eslint-plugin-prettier/recommended';
6
7const eslintConfig = defineConfig([
8  ...nextVitals,
9  ...nextTs,
10  {
11    rules: {
12      '@typescript-eslint/no-unused-vars': 'warn',
13    },
14  },
15  prettierRecommended,
16  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
17]);
18
19export default eslintConfig;

Konfiguracja eslint-plugin-prettier/recommended włącza regułę prettier/prettier i jednocześnie wyłącza reguły ESLinta, które kłóciłyby się z formatowaniem Prettiera, dlatego stoi pod koniec listy. Sprawdzenie całego projektu uruchomisz poleceniem npm run lint.

Konfiguracja Prettier

Prettier to jak automatyczny system organizacji przestrzeni w Metropolii Quantum - dba o spójny wygląd kodu. Utwórz plik .prettierrc w katalogu projektu:

1{
2  "semi": true,
3  "trailingComma": "all",
4  "singleQuote": true,
5  "printWidth": 80,
6  "tabWidth": 2
7}

Konfiguracja VSCode dla projektu

Aby edytor VS Code był w pełni zintegrowany z Twoim projektem, utwórz katalog .vscode w katalogu głównym projektu, a następnie plik settings.json wewnątrz:

1{
2  "editor.formatOnSave": true,
3  "editor.defaultFormatter": "esbenp.prettier-vscode",
4  "editor.codeActionsOnSave": {
5    "source.fixAll.eslint": true
6  },
7  "typescript.tsdk": "node_modules/typescript/lib",
8  "typescript.enablePromptUseWorkspaceTsdk": true
9}

Konfiguracja zmiennych środowiskowych

W Metropolii Quantum każdy system ma swoje specjalne parametry dostępu. W Next.js używamy zmiennych środowiskowych do przechowywania wrażliwych informacji i konfiguracji specyficznych dla środowiska. Utwórz plik .env.local w katalogu głównym projektu:

1# Przykładowe zmienne środowiskowe
2DATABASE_URL=your_database_url
3API_KEY=your_api_key
4NEXT_PUBLIC_API_URL=https://api.example.com

Zmienne z prefiksem NEXT_PUBLIC_ będą dostępne również w przeglądarce.

Testowanie instalacji

Aby upewnić się, że wszystko działa prawidłowo, zmodyfikuj trochę kod w pliku src/app/page.tsx i zobacz, czy zmiany są widoczne w przeglądarce. Jeśli tak, Twoje środowisko jest poprawnie skonfigurowane!

Najczęstsze problemy i rozwiązania

Problem z portami

Jeśli port 3000 jest już zajęty, możesz uruchomić Next.js na innym porcie:

1npm run dev -- -p 3001

Problemy z Node.js

Jeśli napotkasz błędy związane z kompatybilnością wersji Node.js, upewnij się, że używasz wymaganej wersji:

1node -v
2# Jeśli wersja jest za stara, zaktualizuj Node.js lub użyj nvm

Problemy z TypeScript

Jeśli napotkasz błędy TypeScript, sprawdź, czy masz zainstalowane odpowiednie typy:

1npm install --save-dev @types/react @types/node

Zaawansowana konfiguracja

Dla bardziej zaawansowanych projektów, podobnie jak zaawansowane systemy w Metropolii Quantum wymagają dodatkowej konfiguracji, możesz dostosować swoje środowisko Next.js:

Dodanie aliasów ścieżek

Zmodyfikuj tsconfig.json, aby dodać aliasy ścieżek:

1{
2  "compilerOptions": {
3    "baseUrl": ".",
4    "paths": {
5      "@/components/*": ["src/components/*"],
6      "@/lib/*": ["src/lib/*"],
7      "@/styles/*": ["src/styles/*"],
8      "@/utils/*": ["src/utils/*"]
9    }
10  }
11}

Konfiguracja testów

Dodaj do projektu Jest i React Testing Library:

1npm install --save-dev jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom

Utwórz plik jest.config.js:

1const nextJest = require('next/jest');
2
3const createJestConfig = nextJest({
4  dir: './',
5});
6
7const customJestConfig = {
8  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
9  testEnvironment: 'jest-environment-jsdom',
10};
11
12module.exports = createJestConfig(customJestConfig);

Następnie utwórz plik jest.setup.js:

1import '@testing-library/jest-dom';

Podsumowanie

Gratulacje! Tak jak inżynier w Metropolii Quantum, który ukończył konfigurację swojego stanowiska roboczego, Ty również masz teraz w pełni skonfigurowane środowisko deweloperskie dla Next.js 16. Twoje holograficzne terminale (czyli edytor kodu) są gotowe, reaktor kwantowy (Node.js) jest uruchomiony, a systemy bezpieczeństwa (TypeScript, ESLint) są aktywne.

W następnej lekcji dowiemy się więcej o inicjalizacji projektu i dostępnych starterach, które pozwolą Ci szybciej rozpocząć pracę nad konkretnymi typami aplikacji.

1<!DOCTYPE html>
2<html lang="pl">
3<head>
4  <meta charset="UTF-8">
5  <title>Virtual DOM - Metropolis Quantum</title>
6  <style>
7    body {
8      font-family: 'Courier New', monospace;
9      background: linear-gradient(135deg, #0f0f23 0%, #1a1a2e 100%);
10      color: #64ffda;
11      padding: 20px;
12      margin: 0;
13    }
14    .container {
15      max-width: 800px;
16      margin: 0 auto;
17      background: rgba(255, 255, 255, 0.1);
18      padding: 20px;
19      border-radius: 10px;
20      border: 1px solid #64ffda;
21    }
22    h1 {
23      color: #64ffda;
24      text-align: center;
25    }
26    .comparison {
27      display: grid;
28      grid-template-columns: 1fr 1fr;
29      gap: 20px;
30      margin-top: 20px;
31    }
32    .method {
33      background: rgba(0, 0, 0, 0.5);
34      padding: 15px;
35      border-radius: 8px;
36      border: 2px solid #448aff;
37    }
38    .method h3 {
39      color: #448aff;
40      margin-top: 0;
41    }
42    .demo-box {
43      background: rgba(100, 255, 218, 0.1);
44      padding: 10px;
45      border-radius: 5px;
46      margin: 10px 0;
47      border: 1px solid #64ffda;
48    }
49    button {
50      background: linear-gradient(45deg, #7c4dff, #e91e63);
51      color: white;
52      border: none;
53      padding: 10px 20px;
54      border-radius: 5px;
55      cursor: pointer;
56      font-weight: bold;
57      margin: 5px;
58    }
59    button:hover {
60      transform: scale(1.05);
61      box-shadow: 0 5px 15px rgba(124, 77, 255, 0.4);
62    }
63  </style>
64</head>
65<body>
66  <div class="container">
67    <h1>Virtual DOM a prawdziwy DOM</h1>
68
69    <div class="comparison">
70      <div class="method">
71        <h3>Tradycyjna manipulacja DOM</h3>
72        <div id="traditional-demo" class="demo-box">
73          Licznik: <span id="trad-count">0</span>
74        </div>
75        <button onclick="traditionalUpdate()">Aktualizuj (wolno)</button>
76        <p>Każda zmiana → Pełny re-render strony</p>
77      </div>
78
79      <div class="method">
80        <h3>Virtual DOM (sposób Reacta)</h3>
81        <div id="virtual-demo" class="demo-box">
82          Licznik: <span id="virt-count">0</span>
83        </div>
84        <button onclick="virtualUpdate()">Aktualizuj (szybko)</button>
85        <p>Zmiana → Diff → Tylko niezbędne aktualizacje</p>
86      </div>
87    </div>
88
89    <div style="margin-top: 30px; background: rgba(124, 77, 255, 0.2); padding: 15px; border-radius: 8px;">
90      <h3>Jak działa Virtual DOM?</h3>
91      <ol style="line-height: 1.8;">
92        <li>React tworzy wirtualną reprezentację DOM w pamięci</li>
93        <li>Przy zmianie stanu - tworzy nowy Virtual DOM</li>
94        <li>Porównuje (diffing) stary z nowym Virtual DOM</li>
95        <li>Aktualizuje tylko zmienione części w prawdziwym DOM</li>
96        <li>Wynik: Szybsze i bardziej wydajne aplikacje!</li>
97      </ol>
98    </div>
99  </div>
100
101  <script>
102    let tradCount = 0;
103    let virtCount = 0;
104
105    // Tradycyjny DOM - wolniejsza metoda
106    function traditionalUpdate() {
107      tradCount++;
108      console.log("Tradycyjna aktualizacja - cały element jest re-renderowany");
109      document.getElementById('trad-count').textContent = tradCount;
110      // Symulacja wolniejszego działania
111      document.getElementById('traditional-demo').style.background = 'rgba(244, 67, 54, 0.3)';
112      setTimeout(() => {
113        document.getElementById('traditional-demo').style.background = 'rgba(100, 255, 218, 0.1)';
114      }, 200);
115    }
116
117    // Symulacja Virtual DOM - szybsza metoda
118    function virtualUpdate() {
119      virtCount++;
120      console.log("Aktualizacja przez Virtual DOM - tylko niezbędne zmiany");
121      document.getElementById('virt-count').textContent = virtCount;
122      // Symulacja szybszego działania
123      document.getElementById('virtual-demo').style.background = 'rgba(76, 175, 80, 0.3)';
124      setTimeout(() => {
125        document.getElementById('virtual-demo').style.background = 'rgba(100, 255, 218, 0.1)';
126      }, 100);
127    }
128
129    console.log("Demo Virtual DOM - Metropolis Quantum");
130    console.log("Kliknij przyciski, aby zobaczyć różnicę w działaniu!");
131  </script>
132</body>
133</html>