chore(algolia): upgrade to the new major

[millotp]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Algolia has released a new major version of the javascript search client.
Since DocSearch is now using the new version, we can also upgrade the docusaurus-theme-search-algolia package to use the latest version of the js client and of DocSearch.
There are a few changes to do in the code to accommodate the new version but nothing breaking, it's mostly around types and imports.

Test Plan

The existing tests are enough to test that every works, I also tried the local website and the search is working, with the user agent containing the latest version.

Test links

Deploy preview: https://deploy-preview-10672--docusaurus-2.netlify.app/

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 45	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🟠 51	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 74	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 68	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 48	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 84	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 74	🟢 100	🟢 100	🟠 86	Report

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	b916803
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/676139a33d05cd000849d05c
😎 Deploy Preview	https://deploy-preview-10672--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[socket-security]

👍 Dependency issues cleared. Learn more about Socket for GitHub ↗︎

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report↗︎

[slorber]

Thanks @millotp

Since this is a new version, where can I check the breaking changes that potentially affect us?

This seems a bit risky to release this as a minor/patch release.

There are a few changes to do in the code to accommodate the new version but nothing breaking, it's mostly around types and imports.

That's how it affects our internal code. But we also expose some things as part of a public API through themeConfig options:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts

https://docusaurus.io/docs/search#connecting-algolia

I'm particularly worried of possible breaking changes to this type that we expose through themeConfig.algolia.searchParameters

import type { SearchOptions } from '@algolia/client-search';

Are there any to be aware of?

Apart from TS APIs, are there behavior changes to be aware of? For example, different defaults?

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ Auto-approved build	-	Dec 19, 2024, 12:59 PM

[slorber]

@millotp I've seen your Algolia compatibility PR.

We could merge this for the next minor, but we could also delay it to the next major. I plan to do a major with a few technical breaking changes (deps/runtime upgrades like Node and TS) so maybe it's a better time to upgrade Algolia as well.

Is there a good reason for this to land in v3 and not v4? Does anything regarding the UI or behavior change? If that's the case we may prefer keeping it for v4 and strict compatibility is not a problem. Also, from my perspective I don't really have a reasonable way to verify that the upgrade is retro-compatible 😅

[millotp]

Since this is a new version, where can I check the breaking changes that potentially affect us?

Hey @slorber, thanks for the review, here is a brief page about all the breaking changes in v5: https://www.algolia.com/doc/libraries/javascript/v5/upgrade/

Most breaking changes have been handled in DocSearch directly, which exposes a common interface, and autocomplete was already compatible with the client v5.

Are there any to be aware of?

Indeed this type is not fully compatible with the previous one, it's partly fixed by algolia/api-clients-automation#4108 but it's not 100% compatible.

Is there a good reason for this to land in v3 and not v4?

No it's perfectly fine to stay on the client on this version and wait for a next major, my first goal was to upgrade algoliasearch in the yarn cli as a test to make sure that v5 works well in the real world, but it depends on this theme.
Trying to upgrade in this PR already resolved some issues so it was still worth it !

Does anything regarding the UI or behavior change

The only change is a bug fix in docsearch to close the modal with Cmd+K

I can try to make the constraint algoliasearch >= 4.18.0 < 6 to be compatible with all versions also

[slorber]

Thanks @millotp

Most breaking changes have been handled in DocSearch directly, which exposes a common interface, and autocomplete was already compatible with the client v5.

Great. As far as I understand you decided for DocSearch it was not worth it to release a new major version and released the Algolia v5 upgrade in DocSearch v3.6.3 patch release right?

So, does this mean that you consider it compatible enough to do this safely? (or maybe you explicitly not respect semver?)

Are there any to be aware of?

Indeed this type is not fully compatible with the previous one, it's partly fixed by algolia/api-clients-automation#4108 but it's not 100% compatible.

If it's not 100% compatible, why did you decide to upgrade Algolia from v4 to v5 in a patch release? That seems risky to me, this means DocSearch users will upgrade to Algolia v5 by just regenerating their lockfile.

Is this intended, or do you consider that the differences are so subtle that they shouldn't break any site using DocSearch v3? What are those differences exactly?

Note that on our theme, we depend on DocSearch ^3 and Algolia ^4.

In practice this means that since you didn't release this upgrade in a new major version, newly initialized Docusaurus sites, and sites upgrading their lockfile, are already using Algolia v5 for the DocSearch modal, but they still use Algolia v4 for the /search page.

The Algolia dependency is now duplicated, which wasn't the case before.

What I mean is, Docusaurus users already use Algolia v5. At best, we could prevent this upgrade by pinning the DocSearch dependency to v3.6.2 (before the upgrade).

I assume it's fine to merge this PR because nobody complained about any compatibility issues so far. Just wanted to let you know that it feels a bit risky to do such an upgrade in a patch release 😅 and it also inadvertently increased our site bundle size by duplicating the Algolia dependency in 2 distinct versions.

I can try to make the constraint algoliasearch >= 4.18.0 < 6 to be compatible with all versions also

I'm not sure I understand 🤔

[slorber]

Looks good to me, didn't see any regression.

Still curious to have your feedback on a few things

[slorber]

Is this what fixes cmd+K?

[millotp]

cmd+k was fixed in docsearch directly, this fixes an issue where the search would always start with the same character if it was already focused once.

[shortcuts]

noice

[socket-security]

Report too large to display inline

View full report↗︎

[millotp]

Hello @slorber, sorry for the delay.

While there are many breaking changes in algoliasearch v5, most of them are abstracted in docsearch and the migration should be without any changes for most users.

There are some changes to the type like transformSearchClient to make it compatible with both the lite client and the full algoliasearch client, and a change to the searchParameters to be more correct and aligned with what the API expect.

Thank you for the reviews, the changes are pretty minimal now :)