Have official documentation on how to integrate pagefind into meta-frameworks like Next.js, Nuxt, SvelteKit, etc.

[hankertrix]

Currently, there's not much out there in terms of documentation on integrating pagefind with these popular JavaScript meta-frameworks.

There is issue #327 that I wrote, but that is more of an ugly hack that relies on the framework somehow building successfully in the dev environment and then moving the built pagefind files to the static directory so that the pagefind library can be found when building for production, which I think most would not want to rely on.

[bglw]

Agreed.

I'm likely not the best person to write this documentation; I'm not a heavy user of the current framework landscape, and I'd be likely to miss a lot of idioms when putting sites together. It's also a hard thing to document, as the easy integrations aren't particularly nice, as #327 covers.

---

A brief aside on improving the experience more generally

_I have some hope that the [NodeJS API](https://pagefind.app/docs/node-api/) can be of use to the framework-based site generators — possibly by hooking deeper into the internals and generating the Pagefind index alongside the build. ([ex: Lume](https://github.com/lumeland/lume/blob/0f2df8780a34ee5b2e0a41e506485699bdcc07ac/plugins/pagefind.ts#L142-L153)). Since this couples tightly with a given framework, though, it isn't something I would have time to maintain as an official plugin. Tt would require someone with a vested interest to build and maintain it._ _In the same vein, if there are any improvements that can be made to the CLI or the Node API to better integrate into these systems, this is the kind of generic feature implementation I'm happy to take on_ 🙂

---

In terms of just improving the documentation, there are two paths:

1. The Resources page of pagefind.app is overdue for a zhuzh up — if others are putting in effort to write up guides, I like linking off to their sites where possible 🙂
2. Official docs do bring with them some weight and confidence — If anyone is keen to contribute official documentation for any tooling, get in touch — either in this issue or open a PR with some initial changes. I'm happy to help review (and as an inexperienced user of these types of tooling, am likely a useful test dummy)!.

@hankertrix I hope that helps set the scene a little, even though I don't have any immediate contributions to offer myself 😅

[hankertrix]

I'm likely not the best person to write this documentation; I'm not a heavy user of the current framework landscape, and I'd be likely to miss a lot of idioms when putting sites together. It's also a hard thing to document, as the easy integrations aren't particularly nice, as https://github.com/CloudCannon/pagefind/issues/327 covers.

I see, no worries! Hopefully, there will be more people willing to write documentation when they figure out how to make pagefind work with the framework they are using. I'll continue to hack around and figure out a saner way to build SvelteKit sites with pagefind. Currently, the @vite-ignore comment is looking quite promising for successfully building SvelteKit even if the pagefind path isn't found, but I haven't tested it yet. I'm also still not very sure if the @ts-expect-error comment is needed along with the @vite-ignore comment.

I have some hope that the NodeJS API can be of use to the framework-based site generators — possibly by hooking deeper into the internals and generating the Pagefind index alongside the build. (ex: Lume).

I'm hoping this will eventually happen as pagefind gets increasingly popular (man it has come a long way since I started using it), and people will make Vite or Webpack plugins for it.

If anyone is keen to contribute official documentation for any tooling, get in touch — either in this issue or open a PR with some initial changes.

I would be happy to write official documentation for SvelteKit once I figure out a way that doesn't require you to build the entire site in the development environment to generate the pagefind bundle to get it to build properly in the production environment. However, using pagefind's highlighting script is still non-trivial and would most likely be non-trivial for most of these JavaScript meta-frameworks as almost all of them do server-side rendering (SSR) by default. Having the highlighting script work on every page would necessarily mean changing your entire application to be entirely client-side rendered (CSR), or a single-page application (SPA), which is far from ideal for mostly static sites since you lose out on static-site generation (SSG). Or you could write a handler to handle the highlighting query parameters when requesting from the page from the server, but that would mean giving up static-site generation (SSG) for every single page as well, even if everything on the page is static, which isn't quite worth it.

[Hugos68]

Just a FYI @hankertrix I made a vite-plugin for pagefind that all handles this for you, you can simply install the plugin and use:

// @ts-expect-error - Pagefind will be present at runtime
const pagefind = await import('/pagefind/pagefind.js');

The plugin will handle running and managing pagefind for you so no need to run it manually after build or anything like that, all is done automatically. The ts expect error is still required because the LSP doesn't see the file being present but that's just a type error, both during development and build pagefind is present.

More info: https://github.com/Hugos68/vite-plugin-pagefind

[ilkersigirci]

Just a FYI @hankertrix I made a vite-plugin for pagefind that all handles this for you, you can simply install the plugin and use:

// @ts-expect-error - Pagefind will be present at runtime
const pagefind = await import('/pagefind/pagefind.js');

The plugin will handle running and managing pagefind for you so no need to run it manually after build or anything like that, all is done automatically. The ts expect error is still required because the LSP doesn't see the file being present but that's just a type error, both during development and build pagefind is present.

More info: Hugos68/vite-plugin-pagefind

Awesome work, tried it and working perfectly.

[Hugos68]

Very glad to hear! I am currently updating it pretty often and polishing the API, be sure to be on the latest version since there were some bugs in the version from yesterday.