Dokumentacja • DevOps • Cloudflare • Node.js

Cloudflare Pages + Wrangler CLI: Kompletny Przewodnik

Standard Operating Procedure (SOP) – od inicjalizacji projektu po automatyczny deploy z poziomu terminala.

Ten poradnik pokaże Ci, jak skonfigurować projekt tak, aby był future-proof (odporny na przyszłe zmiany) i gotowy do wdrożenia zarówno dla prostego HTML, jak i zaawansowanych frameworków (React, Vue, Vite). Zamiast przeciągać pliki przez przeglądarkę, nauczysz się używać oficjalnego narzędzia CLI od Cloudflare.

📋 Wymagania wstępne

KROK 1: Inicjalizacja projektu (Złota Zasada Nazewnictwa)

Najczęstszym błędem w ekosystemie Node.js i Cloudflare są polskie znaki i spacje w nazwach folderów. Zawsze używaj małych liter i myślników.

⚠️ Uwaga: Nazewnictwo

ŹLE: C:\Projekty\Artykuł Raport WMU
DOBRZE: C:\Projects\raport-wmu

Utwórz folder i zainicjalizuj plik package.json:

PS> mkdir raport-wmu
PS> cd raport-wmu
PS> npm init -y

KROK 2: Instalacja Wranglera

Zainstaluj Wrangler jako zależność deweloperską (devDependency). Dzięki temu narzędzie będzie przypisane do tego konkretnego projektu i nie zaśmieci globalnie Twojego systemu. 

PS> npm install wrangler --save-dev

KROK 3: Autoryzacja (Logowanie do Cloudflare)

Zanim cokolwiek wyślesz, Wrangler musi wiedzieć, na jakie konto ma to zrobić. 

PS> npx wrangler login

Co się stanie: Otworzy się przeglądarka. Zaloguj się do Cloudflare i kliknij Allow / Zezwól. W terminalu pojawi się komunikat potwierdzający sukces.

KROK 4: Konfiguracja (Dwie Ścieżki)

W przyszłych projektach masz do wyboru dwie metody konfiguracji. Metoda A to oficjalny standard Cloudflare (zalecana). Metoda B to szybki skrót.

🏆 Metoda A: Plik wrangler.toml (Zalecane / Future-Proof)

Zamiast zaśmiecać package.json, tworzysz w głównym katalogu plik wrangler.toml.

Dla projektu Statycznego HTML (jak Twój raport):

# wrangler.toml
name = "raport-wmu"
# Wskazuje Wranglerowi, gdzie szukać plików do wgrania
pages_build_output_dir = "./"

Dla projektu z Frameworkiem (np. React, Vite, Vue):

# wrangler.toml
name = "moja-aplikacja-react"
# Pliki kompilują się do folderu dist lub build
pages_build_output_dir = "./dist"

⚡ Metoda B: Skrypt w package.json (Szybka)

Otwierasz package.json i dodajesz skrypt w sekcji "scripts":

// package.json
"scripts": {
  "deploy": "wrangler pages deploy ."
}

(Używamy . dla HTML-a, lub ./dist dla Reacta/Vite).

KROK 5: Wdrożenie (Deploy)

Jeśli użyłeś Metody A (plik wrangler.toml):

PS> npx wrangler pages deploy

Jeśli użyłeś Metody B (skrypt w package.json):

PS> npm run deploy

🚀 Efekt

Wrangler spakuje pliki, wyśle je do globalnej sieci Cloudflare i zwróci Ci link typu https://raport-wmu.pages.dev. Strona jest live w kilka sekund!

🧠 KROK 6: Jak to działa z Frameworkami? (React, Vite, Next.js)

Kiedy przejdziesz z czystego HTML na frameworki, zasada jest zawsze ta sama: Wrangler nie wdraża Twojego kodu źródłowego, wdraża tylko "zbuildowane" (skompilowane) pliki.

  1. Tworzysz projekt: npm create vite@latest my-app
  2. Instalujesz Wrangler: npm install wrangler --save-dev
  3. Tworzysz wrangler.toml z wpisem pages_build_output_dir = "./dist"
  4. Budujesz projekt: npm run build (to tworzy folder dist)
  5. Wdrażasz: npx wrangler pages deploy

🛡️ Złote Zasady i Troubleshooting (Ściąga)

Problem Przyczyna Rozwiązanie
npm error Invalid name Folder ma spacje lub polskie znaki (np. ł, ó). Zmień nazwę folderu na moj-projekt (bez ogonków i spacji).
ENOENT: no such file or directory 'package.json' Nie zainicjalizowałeś projektu Node.js. Wpisz npm init -y w katalogu projektu.
Error: No pages build output directory found Wrangler szuka folderu dist, a Ty masz tylko HTML. Użyj pages_build_output_dir = "./" w wrangler.toml lub . w skrypcie npm.
Chcesz usunąć projekt z Cloudflare Zmieniłeś nazwę i chcesz posprzątać. Wejdź w panel Cloudflare -> Workers & Pages -> Usuń projekt.

💡 Pro-Tip: Git i .gitignore

Jeśli wrzucasz projekty na GitHuba (aby podpiąć je pod Cloudflare przez Continuous Deployment), nigdy nie wrzucaj folderu node_modules.

Zawsze twórz plik .gitignore w głównym katalogu i wpisz w nim:

node_modules/
dist/
.wrangler/

Dzięki temu Twoje repozytorium będzie lekkie, a Cloudflare i tak sam zbuduje projekt po stronie serwera (jeśli użyjesz integracji z GitHubem).