How deployment works

← Previous Next →
Site Operations · 1 of 6

How deployment works

This is a Worker with static assets, not a Pages project, and the difference decides whether server code runs at all.

Key rule

This project is a Worker with static assets, not classic Cloudflare Pages. Its dashboard domain ends in .workers.dev, not .pages.dev. Almost every confusing deployment problem traces back to that distinction.

Pushing to main on GitHub triggers a build. The build runs npx wrangler deploy, which reads wrangler.jsonc, uploads the static files, and installs worker.js as the entry point. Deploys usually complete in under a minute.

Why the distinction matters

Classic Pages projects automatically compile a functions/ directory into live routes. A Worker project does not. Without wrangler.jsonc naming worker.js as main, every file under functions/ is simply uploaded as a static file and served as plain text, exactly like the old PHP scripts were.

That is what caused /api/contact to return 404 while the file sat there in the repo looking correct. The symptom to recognize: requesting the function's own path returns 200 with content-type: text/javascript, meaning you are downloading the source rather than running it.

Adding an API route

Routing is hand-written in worker.js, deliberately, rather than going through wrangler pages functions build. That build step produces a bundle aimed at the Pages runtime and adds machinery this site does not otherwise need.

To add a route, write the handler under functions/api/ exporting onRequest({ request, env }), then add one line to the ROUTES table in worker.js. Anything not in that table falls through to the static site via the ASSETS binding.

PHP is gone, permanently

Cloudflare never executes PHP. Every .php file on the old HostGator site was dead from the moment the domain moved, and worse, each one served its own source code to anyone who requested it. All of them have been removed. sitemap.php was replaced by a generated sitemap.html, and the PHPMailer scripts by Worker functions.

When a deploy seems not to land

Check in this order:

  • Did the push reach GitHub? git log origin/main settles it.
  • Is the built output live? Request a file that changed and see whether the new version comes back.
  • Does the build log mention an error? A build can report success and still not take effect.

One deploy in this project reported a clean success but never became current. Clicking Retry deployment in the dashboard fixed it with no code change. Worth trying before assuming a real bug.