Част 5: Cloudflare Pages от терминала — Wrangler CLI на практика

Тук говоря за Cloudflare Pages Direct Upload и Wrangler CLI. Това е подходът, който използвам, когато вече имам готов статичен сайт и искам от терминала да създам Pages project, да го тествам, да го кача и при необходимост да управлявам deployments. Cloudflare продължава да поддържа wrangler pages ... за Pages, а за локално инсталиран Wrangler препоръчва използването му през package manager като npx.

1. Защо използвам Wrangler, а не Dashboard?

Dashboard-ът на Cloudflare е удобен и не го избягвам. Когато обаче вече имам готова директория със сайта, за мен е по-бързо да отворя терминала и да изпълня една команда.

Това има и още едно предимство: командата може да бъде записана в shell history, в script или в CI/CD workflow. Така не завися от това къде се намира даден бутон в Dashboard-а.

2. Какво ми е необходимо?

За този начин на работа ми трябват Node.js, npm и Cloudflare акаунт. Wrangler се поддържа като локален dependency и Cloudflare препоръчва локална инсталация вместо глобална.

Затова в моите команди ще използвам npx wrangler. Не е необходимо да правя глобална инсталация на Wrangler.

Проверявам Node.js и npm

node --version
npm --version

3. npx или глобален Wrangler?

Аз бих избрал npx. Причината е проста — не искам една глобална версия на Wrangler да управлява всички мои проекти. При локална инсталация версията е част от самия проект и мога да я обновявам контролирано.

Ако проектът няма локално инсталиран Wrangler, npx може да го изпълни. За проект, който поддържам дълго време, предпочитам да го добавя като development dependency:

Инсталирам Wrangler локално

npm install --save-dev wrangler

След това мога да проверя коя версия използвам:

Версия на Wrangler

npx wrangler --version

4. Влизам в Cloudflare

Първата команда, която използвам на нова машина, е:

Cloudflare login

npx wrangler login

Wrangler отваря браузъра и извършвам authentication през Cloudflare. След успешния login проверявам кой потребител е активен:

Проверка на authentication

npx wrangler whoami

Моят навик: когато работя на нов host, първо изпълнявам whoami. Така не започвам deployment към грешен Cloudflare акаунт.

5. Създавам нов Cloudflare Pages project

Ако проектът още не съществува, мога да го създам директно от терминала:

Създаване на Pages project

npx wrangler pages project create my-site

Cloudflare ще поиска името на production branch. При Direct Upload това е част от настройката на проекта. След създаването сайтът получава адрес от вида my-site.pages.dev, ако името е свободно.

Мога да задам production branch директно:

Създаване с production branch

npx wrangler pages project create my-site --production-branch=main

6. Мога ли да създам проекта и с deploy?

Да. Cloudflare позволява първият pages deploy да създаде проекта, ако той още не съществува. За мен обаче отделните стъпки са по-ясни: първо създавам проекта, след това качвам файловете.

Алтернативен първи deploy

npx wrangler pages deploy ./dist --project-name=my-site

Не бих разчитал сляпо на автоматичното създаване. Ако работя с повече проекти, предпочитам pages project create да е отделна стъпка. Така знам точно кой project създавам и какво име използвам.

7. Качвам готовия сайт

Това е командата, която вероятно ще използвам най-често. Ако статичният сайт е в директория dist:

Production deploy

npx wrangler pages deploy ./dist --project-name=my-site

При сайт, който вече е готов в текущата директория, мога да посоча конкретната папка. Например:

Качвам директорията на сайта

npx wrangler pages deploy ./site --project-name=my-site

Важно е да посоча директорията с готовите файлове, а не архива на проекта. При Wrangler Direct Upload се качва една директория с assets; zip файл не е поддържаният вход за Wrangler.

8. Как правя preview deployment?

Когато не искам веднага да променям production версията, използвам branch чрез --branch:

Preview deployment

npx wrangler pages deploy ./dist --project-name=my-site --branch=testing

Това е много по-безопасно, когато съм направил по-голяма промяна и първо искам да я видя в preview среда.

9. Локално тествам Pages сайта

Преди да качвам нещо, мога да го стартирам локално с pages dev:

Локален preview

npx wrangler pages dev ./dist

Wrangler стартира локален development server. По подразбиране Pages използва порт 8788. Така мога да проверя сайта, преди да направя deployment.

При нужда мога да включа live reload:

Локален preview с live reload

npx wrangler pages dev ./dist --live-reload

Това е особено полезно за статични сайтове. Мога да проверя относителни пътища, JavaScript, CSS, redirects и други зависимости локално, преди да кача поредната версия.

10. Показвам всички Pages проекти

Когато не помня точното име на някой project, не търся из Dashboard-а:

Списък на проектите

npx wrangler pages project list

Ако ми трябва машинно четим резултат:

JSON output

npx wrangler pages project list --json

11. Проверявам deployments

За конкретен project мога да видя deployment-ите му:

Списък на deployments

npx wrangler pages deployment list --project-name=my-site

Мога да филтрирам по environment (production или preview):

Само production deployments

npx wrangler pages deployment list --project-name=my-site --environment=production

Това е полезно, когато искам да разбера коя версия е качена, какви preview deployment-и са останали или просто да видя историята на проекта.

12. Изтривам deployment

Ако имам deployment, който вече не ми трябва, мога да го изтрия по неговия ID:

Изтриване на deployment

npx wrangler pages deployment delete DEPLOYMENT_ID --project-name=my-site

Ако deployment-ът има активен alias, Wrangler по подразбиране ще поиска допълнително потвърждение. При необходимост мога да използвам --force (или -f):

Принудително изтриване

npx wrangler pages deployment delete DEPLOYMENT_ID --project-name=my-site --force

13. Изтривам целия Pages project

Ако проектът вече не ми трябва, командата е:

Изтриване на project

npx wrangler pages project delete my-site

За автоматизирана среда мога да потвърдя директно с --yes (или -y):

Без интерактивно потвърждение

npx wrangler pages project delete my-site --yes

Тази команда не е за експерименти. Преди да изтрия project, проверявам името два пъти. Ако проектът има много deployments, Cloudflare има известен проблем при изтриване на project с над 100 deployments. В такъв случай първо изтривам deployments.

14. Ако имам повече от 100 deployments

Cloudflare описва известен проблем при изтриване на Pages project с повече от 100 deployments. Практическият подход е първо да изтрия старите deployments и след това самия project.

Проверявам deployments

npx wrangler pages deployment list --project-name=my-site --json

След като разполагам с ID-тата, мога да ги изтрия с pages deployment delete. Не бих пускал автоматичен shell loop върху production project, преди да съм проверил какво точно ще изтрие.

15. Следя логове на deployment (tail)

Ако Pages Functions генерират логове и искам да ги видя в реално време, мога да използвам:

Tail на production deployment

npx wrangler pages deployment tail --project-name=my-site --environment=production

Мога да посоча конкретен deployment ID или URL. Това е полезно при дебъгване на Functions, без да отварям Dashboard-а.

16. Свалям конфигурацията на project

Ако искам да работя с Wrangler configuration file (wrangler.toml / wrangler.jsonc) вместо само Dashboard настройки, мога да сваля текущата конфигурация:

Download config

npx wrangler pages download config my-site

Командата е marked като experimental, но е удобна, когато искам локален файл като source of truth за bindings, compatibility date и други настройки.

17. npx, npm или C3?

Тук има малко объркване, защото Cloudflare има повече от един CLI workflow. npx wrangler pages ... е много удобен за вече готов статичен сайт и Direct Upload.

Cloudflare има и C3 — Create Cloudflare — чрез:

C3 за нов Pages application

npm create cloudflare@latest -- --platform=pages

Аз бих използвал C3, когато започвам ново приложение и искам Cloudflare да ми помогне със структурата, framework-а и зависимостите. За вече готов HTML/CSS/JavaScript сайт бих останал с Direct Upload и Wrangler.

18. Direct Upload срещу Git integration

Това е нещо, което е добре да се реши в началото. При Direct Upload аз контролирам кога качвам новата версия. Това е удобно за статични сайтове, които редактирам локално и публикувам ръчно.

При Git integration Cloudflare може автоматично да build-ва и deploy-ва при промяна в Git repository. Това е по-подходящо за проект с постоянен CI/CD workflow.

Важно: Cloudflare посочва, че Direct Upload и Git integration не могат просто да се превключат един в друг. Ако избера грешния модел в началото, може да се наложи да създам нов project.

19. Моят практичен workflow

За малък статичен сайт моят workflow е съвсем прост:

Редактирам

HTML / CSS / JS

→

pages dev

локален тест

→

pages deploy

upload

→

Cloudflare Pages

production

Например:

Моят типичен цикъл

npx wrangler pages dev ./site
npx wrangler pages deploy ./site --project-name=my-site

Това е всичко, което ми трябва за голяма част от статичните сайтове. Не усложнявам workflow-а, ако няма реална причина да го усложнявам.

20. Командите накратко

Команда	За какво я използвам
`npx wrangler --version`	Проверявам версията на Wrangler.
`npx wrangler login`	Влизам в Cloudflare.
`npx wrangler whoami`	Проверявам активния Cloudflare user.
`npx wrangler pages project create NAME`	Създавам Pages project.
`npx wrangler pages dev DIR`	Тествам сайта локално.
`npx wrangler pages deploy DIR --project-name=NAME`	Качвам production deployment.
`npx wrangler pages deploy DIR --project-name=NAME --branch=BRANCH`	Качвам preview deployment.
`npx wrangler pages project list`	Показвам Pages projects.
`npx wrangler pages deployment list --project-name=NAME`	Показвам deployments.
`npx wrangler pages deployment delete ID --project-name=NAME`	Изтривам deployment.
`npx wrangler pages deployment tail --project-name=NAME`	Следя логове на Functions в реално време.
`npx wrangler pages download config NAME`	Свалям конфигурацията като Wrangler файл.
`npx wrangler pages project delete NAME`	Изтривам целия project.

21. Заключение

Cloudflare Pages може да се управлява изцяло от Dashboard-а, но когато работя предимно от терминала, Wrangler ми спестява излишното обикаляне из интерфейса.

За моя начин на работа комбинацията Node.js + npm + npx + Wrangler е напълно достатъчна. Създавам project, тествам локално, правя deploy и при необходимост управлявам deployments — всичко от терминала.

Не използвам C3 само защото го има. Използвам го, когато започвам ново приложение. Когато вече имам готов статичен сайт, Direct Upload с Wrangler е по-простият вариант.

Моят принцип: инструментът трябва да опростява workflow-а, а не да го усложнява. За готов статичен сайт не ми трябва цяла система за build и CI/CD, ако една добре проверена команда за deploy върши работа.