Ross Wintle Site

I’m in a bit of a Friday-hacking mood.



So here’s a bookmarklet that you can drag and drop into your browsers Bookmarks bar.



<a href="javascript:(function()%7Bconst editDomain %3D window.location.hostname %3D%3D%3D 'wpengine.com' %3F 'wpmktgatlas.wpengine.com' %3A 'wpmktgatlasstg.wpengine.com'%3B%0Aconst slug %3D window.location.pathname.split('%2F').findLast(item %3D&gt; item !%3D%3D '')%0Afetch( %60https%3A%2F%2F%24%7BeditDomain%7D%2Fwp-json%2Fwp%2Fv2%2Fpages%3Fslug%3D%24%7Bslug%7D%60).then(response %3D&gt; %7B%0Aresponse.json().then( page %3D&gt; %7B%0Awindow.location %3D %60https%3A%2F%2F%24%7BeditDomain%7D%2Fwp-admin%2Fpost.php%3Faction%3Dedit%26post%3D%24%7Bpage%5B0%5D.id%7D%60%0A%7D)%7D)%7D)()%3B">Edit Page</a>



When you are on a wpengine.com page, clicking on this will (most of the time?) take you to the edit screen in the back end for that page.

A Bookmarklet for Page Editing

<a href="https://circleci.com/docs/getting-started/">The CircleCI docs</a> are good, but there&#8217;s a lot of them and I think we only use a small subset of its functionality.



This post is just a note of some of what I learned while reviewing a CircleCI config file.



Before you read the docs I would strongly recommend reading through the <a href="https://circleci.com/docs/concepts/">Concepts page</a> which covers in more depth most of what I&#8217;m describing here.



<h3 class="wp-block-heading">&#8220;Pipelines&#8221;, &#8220;Workflows&#8221;, &#8220;Jobs&#8221;, &#8220;Steps&#8221;</h3>



Pipelines are defined in CircleCI config files. A pipeline is the full set of processes you run when you trigger work on your projects. Pipelines encompass your workflows, which in turn coordinate your jobs.



Pipelines can be triggered by events (such as a Git push), schedules or the CircleAPI.



Workflows are ordered lists of jobs. You can specify that jobs run in series by saying that one job <code>depends</code> on another in the configuration. Jobs in a workflow can also run in parallel or on a schedule.



Jobs are collections of steps executed in order.



Steps are the individual &#8220;commands&#8221; run by a job. They are either Circle&#8217;s build in commands such as <code>run</code> or <code>checkout</code>. There is a list in the <a href="https://circleci.com/docs/configuration-reference/#steps">configuration reference</a>.



Steps can also run re-usable, custom commands from <a href="https://circleci.com/docs/orb-concepts/#commands">Orbs</a>.



<h3 class="wp-block-heading">&#8220;Cache&#8221; vs &#8220;Workspace&#8221;</h3>



These features both store files between steps &#8211; the difference is how long the files persist.



Workspaces: Each workflow has a temporary workspace associated with it. The workspace can be used to pass along unique data built during a job to other jobs in the same workflow.



These are good for saving the working directory of a build between jobs within a workflow.



Caches: Caching &#8230; reuses the data from previous jobs&#8230; After an initial job run, subsequent instances of the job run faster, as you are not redoing work.



This is used as a persistent filesystem that can store files between workflow runs. We use it to cache our npm and composer dependencies to speed up subsequent deploys.



<a href="https://circleci.com/blog/persisting-data-in-workflows-when-to-use-caching-artifacts-and-workspaces/">This article covers it well</a> if you want to read more.

CircleCI cheat sheet

I previously had a working local install of both <a href="https://github.com/wpengine/atlas-wpengine.com-frontend">atlas-wpengine.com-frontend</a> (the Next.js-based front end of the new website) and <a href="https://github.com/wpengine/atlas-wpengine.com-backend/">atlas-wpengine.com-backend</a> (the Docker-based back-end).



At some point I pulled changes from Github and did some tinkering and this broke.



This posts documents some of the issues I had getting it back up and running.



<h3 class="wp-block-heading">1. Inconsistent branches</h3>



Turns out one of the causes of my issues was that I had inconsistent branches. I was using <code>master</code> branch of the backend repo and the <code>development</code> branch of the frontend repo.



The Drewl front-end developers don&#8217;t run a local copy of WordPress. They connect their local front end sites to the live or staging site.



I can&#8217;t see a simple way to ensure that you&#8217;re always running compatible branches. But be aware that having different or out of date branches can be an issue in this decoupled world.



<h3 class="wp-block-heading">2. Build/dev script issues</h3>



The second issue was that I was confused by the conventions around build/dev scripts and my lack of understanding of npm &#8220;Workspaces&#8221;. AND&#8230; I didn&#8217;t read the README! 🤦



I was running:



<code>npm run faust:start -w apps/front-website</code>



This used to work for me locally, and I thought that this was running a dev server. But this runs a production server and was asking me to run the production build first so that it had something to serve.



However, running



<code>npm run faust:build -w apps/front-website</code>



gave me errors and a failing build because of issue 1 (see above).



What I needed to do locally was to run:



<code>npm run faust:dev -w front-website</code>



(Part of my confusion is that I&#8217;ve used JS frameworks in the past where <code>start</code> was the development command. Electron, for example&#8230;)



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="394" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22-1024x394.png" alt="" class="wp-image-419" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22-1024x394.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22-300x116.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22-768x296.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22-1536x591.png 1536w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/06/Screenshot-2023-06-06-at-18.02.22.png 1574w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



It seems that <code><a href="https://docs.npmjs.com/cli/v7/using-npm/scripts?v=true#npm-start">npm start</a></code> is the convention for starting a production server. So watch out for that.



ASIDE: Workspaces, scripts, and faust/Atlas



I also note that this project uses <a href="https://docs.npmjs.com/cli/v9/using-npm/workspaces">npm Workspaces</a>. This is like sub-modules &#8211; it allows multiple npm packages to be present in a single repository (the &#8220;monorepo&#8221; approach).



What confused me is that the front end repository also has a root <code>package.json</code> with some npm scripts in:



<pre class="wp-block-code"><code>"wpe-build": "npm run faust:build -w $WORKSPACE",
"start": "npm run faust:start -w $WORKSPACE",</code></pre>



I wasn&#8217;t sure how the $WORKSPACE got passed into this.



Turns out you can ignore this on local dev. This is actually a Faust/Atlas thing. These two commands are <a href="https://developers.wpengine.com/docs/atlas/customization/builds#custom-build-commands">used by Atlas to build and start the site</a>.



While I&#8217;ve not discovered the exact mechanism by which environment variables get into <code>package.json</code>, the <code>$WORKSPACE</code> is an environment variable and is set in the Atlas environment variables configuration in the WPE Portal.



The scripts you want to run in local dev are those in <code>apps/front-website/package.json</code> and yes, these are documented in <a href="https://github.com/wpengine/atlas-wpengine.com-frontend/">the README</a>!

Web3: Getting local dev working – Faust scripts and branches

Summary:



I found that publishing new posts on Atlas did not work as expected. New posts did not appear immediately. I was told that this was normal and I had to wait for the <code>revalidate</code> timeout to happen. But this still wasn&#8217;t right. I did a deep dive into how Atlas does caching and revalidating. I found that:



<ul class="wp-block-list">
<li>you can have a mix of fresh/stale content for a while after publishing new content</li>



<li>it can take double the <code>revalidate</code> time to see the new content</li>



<li>different users may see different content depending on where they are in the world</li>
</ul>



<hr class="wp-block-separator has-alpha-channel-opacity"/>



<h2 class="wp-block-heading">Atlas and Incremental Static Regeneration (ISR)</h2>



There are three different kinds of server-side content generation in Next:



<ul class="wp-block-list">
<li>Static Site Generation (SSG) &#8211; this builds the whole site from nothing. It is slow but comprehensive and ends up with cached, static content. Rebuilds are needed whenever content changes.</li>



<li>Server-side Rendering (SSR) &#8211; this builds a page each time Next gets a request. It&#8217;s like PHP. It keeps content dynamic &#8211; no rebuilds necessary. But is slower to server requests and loads the Node server. You can help this by putting caching in front of Next.</li>



<li>Incremental Static Regeneration (ISR) &#8211; this builds and serves static pages, but it does them one at a time and clears the cache (regenerates/revalidates) according to some rule.</li>
</ul>



There are two kinds of <a href="https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration">ISR in Next</a>.



“On-demand” ISR is when the Next server is notified when there is a content change so that it can re-build. This seems to be what doesn’t work fully in Atlas. WP Engine are working on this. This limitation is documented in the <a href="https://developers.wpengine.com/docs/atlas/framework-guides/faust#known-limitations">Framework Guides sections of the Atlas docs</a>.



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
While our Node infrastructure will support path-based revalidation on-demand, this revalidation will currently not extend to edge cached versions of that path, nor will they apply to all instances of your front-end application (if scaled beyond a single instance). This is under active investigation by our engineering team.
</blockquote>



&#8220;Path-based ISR&#8220;: I think this is what “Non-on-demand” ISR is called . This is where the <code>revalidate</code> setting comes in. By default Atlas/Faust (not sure which) has a <code>revalidate</code> setting of 900 seconds or 15 minutes.



When the <code>revalidate</code> timeout is reached, Next will serve the old page and trigger a refresh of the content in the background, so that the new content is served next time.



<h2 class="wp-block-heading">Cloudflare and Next both cache content</h2>



Atlas puts Cloudflare in front of Next, and the revalidate timeout is also used as the cache timeout in Cloudflare.



Cloudflare&#8217;s cache has to expire to trigger a revalidate in Next.



So here’s what happens when you change the content in an Atlas site with a 15 minute <code>revalidate</code>.



<ul class="wp-block-list">
<li>(Mins:Secs &#8211; times are examples and may vary)</li>



<li>00:00 &#8211; Content is changed in WordPress. Cached content in Next is not changed. Cached content in Cloudflare is NOT changed.</li>



<li>(no later than) 15:00 &#8211; Cloudflare cache expires</li>



<li>15:10 &#8211; Page is hit. Cloudflare refreshes content. This hits Next. Next serves the old page to Cloudflare, which caches it. Next triggers a refresh in the background. User sees old page</li>



<li>15:20 &#8211; Page is hit. Next has the new page now, but Cloudflare still has the old page. User sees old page</li>



<li>30:10 &#8211; Cloudflare cache expires again.</li>



<li>30:20 &#8211; Page is hit. Cloudflare refreshes content. This hits Next again. Next now serves the new page, and triggers another refresh as its revalidate timeout has expired again as well. User sees new page.</li>
</ul>



In short, with this setup, it can take up to two Cloudflare CDN expiries to see the new content!! On a low-traffic site (such as a developer like me testing Atlas out by themselves) this is going to tend towards the 2 x the revalidate time.



This is complicated by the fact that the CDN has multiple caches in different “Edge” locations. And, on a busy site, Atlas can spin up multiple instances of Node/Next. So you can have a mix of old and new content served from different places for some time after the <code>revalidate</code> timeout.



<h2 class="wp-block-heading">Cache clearing</h2>



It&#8217;s worth noting that there are a couple of ways to refresh the content.



Rebuild / Clean Rebuild in the WPE Portal



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="671" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-13.52.00-1024x671.png" alt="" class="wp-image-408" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-13.52.00-1024x671.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-13.52.00-300x197.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-13.52.00-768x503.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-13.52.00.png 1435w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



These options rebuild the Next app from the sources in Git. From what I can tell the &#8220;Clean rebuild&#8221; option is the one that also does a full rebuild of the site content. Though the current descriptions of these options are not clear to me.



Purge cache



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="672" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.11.31-1024x672.png" alt="" class="wp-image-409" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.11.31-1024x672.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.11.31-300x197.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.11.31-768x504.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.11.31.png 1433w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



This option clears the CDN/Cloudflare caches, but does not clear the Next cache. So, oddly, this will not show fresh content. But it will (on the next page visit) trigger an ISR of pages in Next. So new content won&#8217;t appear immediately, but it will appear sooner than if you hadn&#8217;t done the cache purge.



I guess this will also purge the asset cache of images, CSS, JS, etc.



<h2 class="wp-block-heading">Tracing / Debugging with headers in dev tools.</h2>



Now that we know a bit about how this works, we can use the HTTP response headers to check our understanding and do diagnosis. I&#8217;m not 100% on the details here, but I&#8217;ll give it my best go.



There are (at least) 4 relevant headers:



<ul class="wp-block-list">
<li><code>age</code> &#8211; this is from Cloudflare and tells you how many seconds old the page is</li>



<li><code>cache-control</code> &#8211; this will have a value like <code>s-maxage=900, stale-while-revalidate</code> and the maxage should be the same as the <code>revalidate</code> setting for the page in Next</li>



<li><code>cf-cache-status</code> &#8211; the Cloudflare cache status &#8211; should be <code>HIT</code> or <code>EXPIRED</code></li>



<li><code>x-nextjs-cache</code> &#8211; the Next cache status &#8211; this should be <code>STALE</code> or <code>HIT</code>, but note that this is not the current state of the Next cache, but rather the cached state stored in Cloudflare. So you can see <code>STALE</code> here for a while when you would normally only see <code>STALE</code> occasionally with ISR, on those hits that trigger a revalidate</li>
</ul>



Let&#8217;s follow the steps through with a site using the Atlas Portfolio Blueprint.



1. Make a new post in WordPress



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="675" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.27.45-1024x675.png" alt="" class="wp-image-411" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.27.45-1024x675.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.27.45-300x198.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.27.45-768x507.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.27.45.png 1425w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption class="wp-element-caption">Publish it!!</figcaption></figure>



2. Open Dev Tools and reload the home page of the site



This disables browser caching and lets us see network requests. The new post doesn&#8217;t show in the &#8220;Latest posts&#8221;.



Both the Next AND Cloudflare caches are hit and we get old content.



If we select the main HTTP request and view the response headers we can see this.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="672" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.32.32-1024x672.png" alt="" class="wp-image-412" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.32.32-1024x672.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.32.32-300x197.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.32.32-768x504.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.32.32.png 1438w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



3. Clear the Cloudflare cache and try again



Use the &#8220;Purge cache&#8221; button in the WP Engine Portal to clear the Cloudflare cache.



Reloading the homepage should show the <code>cf-cache-status</code> has expired. In the screenshot below this has happened BUT, the Next cache is still showing us a <code>HIT</code> so we&#8217;ve not hit the revalidation time in Next yet.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="671" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.33.13-1024x671.png" alt="" class="wp-image-413" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.33.13-1024x671.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.33.13-300x196.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.33.13-768x503.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.33.13.png 1437w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



4. Clear the Cloudflare cache and try again



We&#8217;ll need to wait a while longer and repeat the Purge cache -&gt; Reload the page cycle until we see both caches have expired:



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="670" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.40.21-1024x670.png" alt="" class="wp-image-414" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.40.21-1024x670.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.40.21-300x196.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.40.21-768x503.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.40.21.png 1436w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



We still don&#8217;t see the new content. This has triggered the refresh in Next, but Next served the old page to Cloudflare. Cloudflare will cache this for another 900 seconds and serves it to us.



5. (You guessed it&#8230;) Clear the Cloudflare cache and try again



Do another Purge cache to clear out Cloudflare, and then reload.



Cloudflare will now get the NEW page from Next&#8230;



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="672" src="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.44.26-1024x672.png" alt="" class="wp-image-415" srcset="https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.44.26-1024x672.png 1024w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.44.26-300x197.png 300w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.44.26-768x504.png 768w, https://h3824xvzb4iv33fq89bovy9d6.js.wpenginepowered.com/wp-content/uploads/2023/05/Screenshot-2023-05-04-at-14.44.26.png 1438w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



We see the new post. Hooray! And the expired Cloudflare response, but the <code>HIT</code> in Next.



We got there &#8211; and the headers showed us what was going on.



<h2 class="wp-block-heading">Thoughts</h2>



This seems over-engineered.



Cloudflare is great because it takes the static content from Next and caches it at the edge, close to users. It keeps the load on the Atlas node server(s) low because Atlas only gets requests for cache misses in Cloudflare.



But I don&#8217;t understand why, if we are doing this, we also need ISR.



It seems to me like we may as well just use Next for SSR and generate pages dynamically. At least for &#8220;marketing&#8221; sites that are effectively static HTML content. (For dynamic sites like eCommerce I suspect there are ways to do fragment caching in Next and this is probably a good leverage of ISR.)



At the very least we could turn the <code>revalidate</code> in Next right down to 10 second or something to quickly serve a static pages for Cloudflare&#8217;s requests, and to regenerate in the back end more frequently to keep content fresh. However, from what I understand this config also controls the cache timeout in Cloudflare, so we&#8217;d need to find a way to override this in Cloudflare, or otherwise disconnect the sync between these values.



I appreciate there are trade offs here, I&#8217;m not an expert in the platform, and there are probably excellent reasons why things are like they are.



<h2 class="wp-block-heading">Links / Resources</h2>



Some things I found along the way:



<ul class="wp-block-list">
<li><a href="https://wpengine.com/support/headless/">WP Engine Headless/Atlas support page</a></li>



<li><a href="https://developers.wpengine.com/docs/atlas/overview">Atlas Platform developer docs</a></li>



<li><a href="https://developers.wpengine.com/docs/atlas/framework-guides/faust">Faust.js framework guide for Atlas</a> &#8211; includes statement on ISR compatibility</li>



<li>There is an <a href="https://developers.wpengine.com/docs/atlas/reference/cli/wpe">Atlas CLI tool</a>!</li>



<li><a href="https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration">Next.js docs on Incremental Static Regeneration (ISR)</a></li>
</ul>

Next, Atlas, Caching, Revalidating

Happy Star Wars Day

Learning about useEffect today. Gosh React is hard work!



The thing I want to remember is how the second parameter (the dependencies array) works.



There are three options for this:



No dependencies array &#8211; this causes the effect to run on initial render and EVERY re-render



<pre class="wp-block-code"><code>useEffect(
 () => {
 // Some side effect
 }
 // No second param - effect runs on EVERY render.
)</code></pre>



Empty dependencies array &#8211; this causes the effect to only run on initial render &#8211; it won&#8217;t run on re-renders



<pre class="wp-block-code"><code>useEffect(
 () => {
 // Some side effect
 },
 &#91;] // Empty second param - effect runs on INITIAL RENDER ONLY.
)</code></pre>



Non-empty dependencies array &#8211; this causes the effect to run a) on initial render b) on any re-render when the state values in the array have changed



<pre class="wp-block-code"><code>&#91;name, setName] = useState({ firstName: 'Ross', lastname: 'Wintle' })

useEffect(
 () => {
 // Some side effect
 },
 &#91;name] // Non-empty second param - effect runs on initial render and when name has changed.
)</code></pre>



The thing I really don&#8217;t get is how the examples used in the Scrimba course cause this double initial render. They use the <code>useEffect</code> hook to run an API query to fetch data after the initial render. This will then trigger a re-render.



So I&#8217;m hoping that a future lesson shows me how to load the data before the initial render. Maybe this would slow down a client-side page load, but it seems like exactly what I would want to do if I was server-side rendering.



UPDATE: It looks like this is exactly what frameworks like Next.js help with! So I&#8217;ll be digging into that soon.

useEffect

Today I was learning more React. The key thing I want to remember is the potential use of the spread operator when passing props.



Instead of:



<pre class="wp-block-code"><code>&lt;Card
 key={card.id}
 title={card.title}
 content={card.content}
></code></pre>



You can pass all the props at once like this:



<pre class="wp-block-code"><code>&lt;Card
 key={card.id}
 data={card}
></code></pre>



OR you can spread the props out:



<pre class="wp-block-code"><code>&lt;Card
 key={card.id}
 {...card}
></code></pre>

Spreading with React

Interesting thing I learned from the Scrimba course today.



If you want to pass number-type props into a React component then you can surround them with braces to escape into JS from the JSX:



<pre class="wp-block-code"><code>&lt;Card 
 img="katie-zaferes.png"
 rating="5.0"
 reviewCount={6}
 country="USA"
 title="Life Lessons with Katie Zaferes"
 price={136}
/></code></pre>



I was actually curious about whether or not this was possible while I was doing the exercise.



I also note, if I haven&#8217;t done so already, that destructuring is a good way to get at props within the component&#8230;



<pre class="wp-block-code"><code>export default function Card(props) {
 const { image, rating, reviewCount, country, title, price } = props;
 return (
 // JSX here can use, for example, image, instead of props.image
 )
}</code></pre>

React: Passing props

I managed to get Faust updated by making a local copy, running npm update, and commiting the <code>package.json</code> to Git.



Though I still confused about why the build without a <code>package.json</code> didn&#8217;t seem to update Faust. Or perhaps it did and we were just running into the next issue?



Anyway, I&#8217;m still having issues with the <a href="https://github.com/wpengine/atlas-blueprint-portfolio">Atlas Blueprint</a>. The posts/blog page seems to update to show new posts without a build now, but the homepage does not.



In fact, there is this weird behaviour where:



<ul class="wp-block-list">
<li>I have 8 posts total.</li>



<li>The posts/blog page shows them all.</li>



<li>The homepage should show posts 1-3, but it’s actually showing posts 3-5</li>



<li>If I visit the blog page and then the homepage, the homepage shows posts 1-5</li>



<li>If I then reload the homepage, it goes back to showing posts 3-5</li>
</ul>



So I&#8217;ve been looking through the Blueprint code to try and understand it. This is NOT easy, but here are some things I&#8217;ve found&#8230;



<ul class="wp-block-list">
<li>There&#8217;s a <code>pages</code> folder and a <code>wp-templates</code> folder.</li>



<li>The <code>wp-templates</code> folder is what mimics the WordPress template hierarchy.</li>



<li>The <code>wp-templates</code> folder includes various things, but, importantly, there is no template here for the <code>/posts</code> route that represents my blog page.</li>



<li>Instead the blog page is a Next.js page with code in the <code>pages</code> folder.</li>



<li>Also in the <code>pages</code> folder is a special file called <a href="https://github.com/wpengine/atlas-blueprint-portfolio/blob/main/pages/%5B...wordpressNode%5D.js"><code>[...wordpressNode].js</code></a> &#8211; I assume that this is what powers the WordPress template hierarchy behaviour. The code in this file makes use of the <code>WordPressTemplate</code> component that <code>faust.js</code> provides.</li>



<li>The file <code>pages/posts/index.js</code> contains the code for the posts/blog page. Importantly, this HAS a <code>getStaticProps</code> that I&#8217;m assuming tcauses the page to be statically generated/cached.</li>



<li>Compare this with the various bits of code used to render the homepage and none of these have <code>getStaticProps</code></li>
</ul>



So what we know here is that the posts page is statically cached and regenerated after a set time.



But the homepage seems to be dynamically rendered (on the server).



I was chatting with Theo Despoudis in #pe-atlas-merlin and he showed me that I could add



<code>fetchPolicy: "no-cache"</code>



to the query setup in <code>front-page.js</code> and this would show me the right posts.



And it did, but it made the homepage really slow.



This is because the server-side generation is using Apollo for fetching and caching queries (Apollo is actually used on both server and client).



This <code>fetchPolicy</code> tells Apollo not to cache the query responses. So the homepage generation is slower.



Shall we try a full summary?



<ol class="wp-block-list">
<li>Posts page is statically generated and working now that the revalidate option is passed</li>



<li>Home page is dynamically (?) generated but using query data that is cached server-side</li>



<li>The Blueprint is broken &#8211; the homepage needs to purge its query cache every now and then, or be statically generated without a query cache, and with a revalidate option set.</li>
</ol>

Category: Uncategorized