My core goal with this post is to break down how Pages, and Pages Functions, work together.

Pages⌗

This link has a good overview of how to set up Pages for deployment. The two that interest me are the Git provider set up, and the wrangler cli. My default is to use the git provider configuration, as I’d like to deploy this on push to the main branch, but the wrangler cli may have some useful functionality to learn about.

There is also this link, which covers how to deploy anything with Cloudflare Pages. From this page, we get the following quote

Unlike many of the framework guides, the build command and build directory for your site are going
to be completely custom. If you do not need a build step, leave the *Build command* field empty and
specify a *Build output directory*. The build output directory is where your application's content
lives.

So to serve up frontend content, the core thing we need is some kind of asset(s) in the build output directory, and potentially we can use a build command if we’d like.

This begs the question: what needs to be in the build output directory for pages to work?

Looking at the output of the hugo command – specifically the files inside it’s output directory – my first though was that just an index.html was sufficient, but I saw a 404.html file, and didn’t see a reference to that in the index.html file, so now I’m not sure.

Luckily, perusing the Platform section of the Pages docs leads me to this page, which explains how Pages chooses to route requests to your assets.

This explains how the 404.html file is served by Pages, and also how the index.html file is served up (plus all the other files).

The non-SPA behavior is described as follows:

** Route matching
   If an HTML file is found with a matching path to the current route
   requested, Pages will serve it. Pages will also redirect HTML pages to
   their extension-less counterparts: for instance, =/contact.html= will be
   redirected to =/contact=, and =/about/index.html= will be redirected to =/about/=.

** Not Found behavior
   You can define a custom page to be displayed when Pages cannot find a
   requested file by creating a =404.html= file. Pages will then attempt to
   find the closest 404 page. If one is not found in the same directory as
   the route you are currently requesting, it will continue to look up the
   directory tree for a matching =404.html= file, ending in =/404.html=.
   This means that you can define custom 404 paths for situations like =/blog/404.html= and =/404.html=, and Pages will automatically render
   the correct one depending on the situation.

Since Fulcro is a React app, we’re probably going to make more use of how it handles SPAs, which is as follows:

If your project does not include a top-level =404.html= file, Pages assumes that you are deploying a
single-page application. This includes frameworks like React, Vue, and Angular. Pages' default
single-page application behavior matches all incoming paths to the root (=/=), allowing you to
capture URLs like =/about= or =/help= and respond to them from within your SPA.

So to get Pages to serve an SPA, we should exclude a 404.html file. I’m not exactly sure if there’s a way to override this at the moment, but can simply avoid creating a 404 file for the time being.

Functions⌗

Now that we’ve got an overview of how to serve a custom frontend – i.e. one that doesn’t use a known framework – let’s take a quick overview of Functions to get a lay of the land.

The overview covers most of what we need to know.

  • There’s a /functions directory which contains js files
  • The filenames, sans-extension, define routes
  • The functions we define in these files have a defined API
  • We can alter the routing logic in some way, though I haven’t dug into how just yet
  • We can also choose an Advanced Mode to define our Functions with a _workers.js file instead of the /functions directory approach

As for how you tie the frontend and backend together, I suspect looking at the Routing docs, the API Reference docs, and the Middleware docs are the proper next things to look at. Routing should help us understand how to ensure FE requests go to the right function in the BE, the API ref will tell us how to actually build the BE functionality, and the middleware docs will tell us how to add things like authentication, as needed.

Next Steps⌗

Two possible avenues open before us:

  • Figure out how to build a barebones Fulcro app with Cloudflare Pages
  • Dig into the aforementioned Functions docs

See you next time!