Caching unhashed pagefind js and css files

[c6p]

Thanks for your work on pagefind. On pagefind site:

The /pagefind/pagefind-ui.css and /pagefind/pagefind-ui.js assets will be created by Pagefind when we index the site.

Are these files safe to cache for extended period (i.e. a year)?

• If not, this is a feature request to add hashes to them - i.e pagefind.ui.[hash].js
• Or do I need to exclude them while sending cache headers for js and css files. Which other files need to be excluded? pagefind.js etc., will they be cache busted?

I've seen #180 , does pagefind-entry.json cache bust other files?

[bglw]

The important thing to know is that these files don't change between runs, but do change between Pagefind releases. So they're safe to cache within any given Pagefind version, but you would want to make sure that the same file is not used when upgrading Pagefind.

The trouble with pagefind-ui.[hash].js is that these files are referenced from your website, so you would need to know [hash] such that you can add <script src="/pagefind/pagefind-ui.[hash].js"></script> to your site reliably.

Instead, what you could do now is update your references into Pagefind to include the version as a query parameter. e.g.

<link href="/pagefind/pagefind-ui.css?v=1.3.0" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js?v=1.3.0"></script>

This parameter won't actually do anything of course, but it will make that URL safe to cache forever. (Under the assumption that you're diligent in updating that version parameter, or include it in your build automation).

---

Pagefind could help with this, by also writing a set of files that are version-hashed. E.g. /pagefind/pagefind-ui.v1.3.0.js. This has a singular pro/con, which is if you forget to update the referenced version when updating Pagefind, the search will fail to load. This is good, because you might catch the error and update the reference. It's also bad, because you might not catch the error and a broken search could be shipped to production.

---

I do also have a goal of publishing these packages on npm for bundling, and marking a future release from which the internal Pagefind API will never break, at which point caching these files forever would be safe (absent trying to use new features).

---

Keen to hear your thoughts on all of the above, or any extra thoughts on implementation 🙂

[c6p]

Thank you for the detailed answer. You're absolutely right, failing to reference version-hashed files could potentially break the site.

In any case, it's best to maintain control over the exact versions of all dependencies.

npx [email protected] --site "public"

Running a specific pagefind version and then, referencing it with the query parameters seems to be the best way, in my case.

---

Regarding my other question, I suspect there's an issue due to caching /_pagefind/pagefind.js (#597). From what I understand, even if I reference a specific version of -ui.js, hashing pagefind.js would break search, is that correct?

Here’s what I see in the pagefind folder:

• .pf_fragment, .pf_index and pf_meta files are hashed and safe to cache
• pagefind-entry.json shouldn't be cached
• For the other js, css, and wasm.*.pagefind files `- are they safe to cache?
  Will they be invalidated automatically when the Pagefind UI version changes?

In other words, is blanket caching safe with something like:

/*.(js|css|pagefind|.pf_*)
  Cache-Control: public, max-age=31536000, immutable

It would be great to see a section on caching added to the documentation.

Cheers 🍻

[bglw]

My talking points about the UI and CSS packages applies to the /_pagefind/pagefind.js file as well, as that file is imported by the end user (in the case of using the UI it isn't, but this is a file you can import into your own js files if you're using Pagefind's API).

The wasm.*.pagefind files not being hashed is an oversight, though. They currently are not safe to cache, but they're only ever loaded internally so they should be changed to incorporate a version/hash to allow caching.

To summarize

• Currently that blanket caching is not safe between Pagefind updates
• Pagefind can implement wasm cache invalidation to make those files safe to cache
• All *.js and *.css files can be referenced by the end user, so are hard to bake cache invalidation into

[c6p]

Thanks @bglw,

Could pagefind-ui.js, ~call~ import pagefind.js and others with a version query parameter?

This woull allow safe long term caching of all js and css assets between versions.

Updating the primary pagefind-ui.js (or pagefind.js) script reference would then automatically fetch the correctly versioned dependencies.