Beginner feedback on CF Pages

[domains104]

Feedback

As someone who is migrating a bunch domains with static content from Gandi to CF Free, I wanted to provide some feedback that might help improve the documentation or experience for other CF beginners.

I have some static web pages that I create and build using my own Gitlab CI. I want to push updates to CF Pages whenever I update that static content. I do not want to integrate my git because I don’t want to give CF access to my private repositories. So I am using wrangler in my CI to push updates to my CF Pages sites whenever I do “a release” (essentially, merge to my main branch, but perhaps in the future, git tag a commit). I want to publish this content on my https://www.example.com URL and https://example.com apex.

I struggled quite a bit to get things working correctly. The CF Pages documentation led me astray a few times, and it required some experimentation and reading between the lines of some related threads on this forum, but eventually I did get things working the way I wanted. Here are some things that tripped me up.

• Production vs preview branches. I think the documentation isn’t great about this. The wrangler command line that the docs told me to use was something like wrangler pages deploy $CONTENT_DIR --project-name=$PROJECT_NAME. However, this pushes the content to HEAD which is not production, thus none of the content is published. You need to add --branch-main to actually publish the site. The documentation could do a better job of pointing this out.
• You have to use wrangler to create the project outside of CI before you can start to push content via CI. You only need to do this once: wrangler pages project create but the docs don’t make this super clear.
• I’ve found that to publish from example.pages.dev to https://www.example.com and https://example.com you actually do not need bulk redirects. The whole bulk redirects thing tripped me up for quite a while because the docs are great about explaining the effects of bulk redirects, and especially how they would come into play when you might have dozens of domains that are publishing pages. The whole redirects + rules system is pretty complicated and the dashboard UI is difficult to navigate. I actually wasted a lot of time on this until I (experimentally) found out you really don’t need any of it, at least for my simple use cases as described above. I’d recommend just ignoring the whole bulk redirects thing in the CF Pages how-tos.
• What actually did work was to use custom domains for both www.example.com and example.com, letting CF set up the DNS for you. There must be something additional magical going on because adding those DNS records directly doesn’t actually get your content published on those URLs, at least in my experience. The best thing to do is to go to Workers & Pages -> example (i.e. your domain) -> Custom domains then Set up a custom domain and add both the www and @ custom domains. Yes, this adds the CNAME records to your DNS, including the flattened version for the apex, but just adding the CNAME records directly does not seem to work. I could be wrong about that, but it does seem like when I tried to do that, my content was not published, and only adding them through the Custom domains tab made everything work properly.
• Out of date references in the docs. There are lots of places where the CF Pages documentation doesn’t match the dashboard UI. I suspect they get out-of-sync pretty easily because the dashboard changes without the docs getting updated. An example is that you have to go to your top level dashboard, then expand Compute (Workers) to find Workers & Pages, which is non-obvious.
• I really wish I didn’t have to use wrangler to publish content. I would have preferred a Python or curl based approach, and I suspect wrangler is just making various API calls, but the documentation is completely opaque about that, and looking at the API docs, it’s very much unclear what the right incantation would be. If I want to do Direct Upload from my CI, I pretty much have no choice but to use wrangler, because its implementation and use of the API is undocumented.

If I think of more things, I’ll follow up here. Despite my complaints (which I hope are taken in the spirit of constructive feedback), ultimately I have been able to publish my static site on CF, and I’m very happy to continue my migration off of Gandi.