search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.84k stars 8.55k forks source link

chore(algolia): upgrade to the new major #10672

Open millotp opened 1 week ago

millotp commented 1 week ago

Pre-flight checklist

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[bot] commented 1 week ago

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO Report
/ 🔴 47 🟢 98 🟢 96 🟢 100 Report
/docs/installation 🟠 54 🟢 97 🟢 100 🟢 100 Report
/docs/category/getting-started 🟠 74 🟢 100 🟢 100 🟠 86 Report
/blog 🟠 64 🟢 96 🟢 100 🟠 86 Report
/blog/preparing-your-site-for-docusaurus-v3 🟠 55 🟢 92 🟢 100 🟢 100 Report
/blog/tags/release 🟠 64 🟢 96 🟢 100 🟠 86 Report
/blog/tags 🟠 76 🟢 100 🟢 100 🟠 86 Report
netlify[bot] commented 1 week ago

[V2]

Name Link
Latest commit 367f60a86ae66a69ae5647a51c2e86514542546e
Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/6735eaf478e0010008ff2622
Deploy Preview https://deploy-preview-10672--docusaurus-2.netlify.app
Preview on mobile
Toggle QR Code...

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[bot] commented 1 week ago

New and removed dependencies detected. Learn more about Socket for GitHub ↗︎

Package New capabilities Transitives Size Publisher
npm/@algolia/autocomplete-plugin-algolia-insights@1.9.3 None 0 133 kB instantsearch-bot
npm/@algolia/autocomplete-preset-algolia@1.17.6 None +1 199 kB abodelot, agdavid, alg-admin, ...82 more
npm/@algolia/autocomplete-shared@1.9.3 None 0 57.5 kB instantsearch-bot
npm/@algolia/cache-browser-local-storage@4.24.0 None 0 8.15 kB shortcuts
npm/@algolia/cache-common@4.24.0 None 0 5.58 kB shortcuts
npm/@algolia/cache-in-memory@4.24.0 None 0 3.63 kB shortcuts
npm/@algolia/client-abtesting@5.12.0 None 0 408 kB shortcuts
npm/@algolia/client-account@4.24.0 None 0 6.78 kB shortcuts
npm/@algolia/client-analytics@4.24.0 None 0 12.3 kB shortcuts
npm/@algolia/client-common@4.24.0 None 0 10.6 kB shortcuts
npm/@algolia/client-insights@5.12.0 None 0 379 kB shortcuts
npm/@algolia/client-personalization@4.24.0 None 0 6.51 kB shortcuts
npm/@algolia/client-query-suggestions@5.12.0 None 0 386 kB shortcuts
npm/@algolia/client-search@4.24.0 None 0 190 kB shortcuts
npm/@algolia/events@4.0.1 None 0 13 kB haroenv
npm/@algolia/ingestion@1.12.0 None 0 1.78 MB shortcuts
npm/@algolia/logger-common@4.24.0 None 0 2.16 kB shortcuts
npm/@algolia/logger-console@4.24.0 None 0 2.37 kB shortcuts
npm/@algolia/monitoring@1.12.0 None 0 405 kB shortcuts
npm/@algolia/recommend@4.24.0 None 0 85.4 kB shortcuts
npm/@algolia/requester-browser-xhr@4.24.0 None 0 6.25 kB shortcuts
npm/@algolia/requester-common@4.24.0 None 0 2.76 kB shortcuts
npm/@algolia/requester-fetch@5.12.0 network 0 17.8 kB shortcuts
npm/@algolia/requester-node-http@4.24.0 network 0 9.21 kB shortcuts
npm/@algolia/transporter@4.24.0 None 0 50.1 kB shortcuts
npm/@docsearch/css@3.6.3 None 0 42.7 kB shortcuts
npm/@docsearch/react@3.6.3 Transitive: network +8 7 MB shortcuts
npm/@docusaurus/module-type-aliases@3.6.0 None +1 12.5 kB slorber
npm/@docusaurus/plugin-content-blog@3.6.0 None 0 232 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-content-docs@3.6.0 None 0 414 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-content-pages@3.6.0 None 0 39.1 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-debug@3.6.0 None 0 37.7 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-google-analytics@3.6.0 None 0 11.5 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-google-gtag@3.6.0 None 0 15.5 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-google-tag-manager@3.6.0 None 0 8.36 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/plugin-sitemap@3.6.0 None 0 35.7 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/preset-classic@3.6.0 None 0 14.1 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/theme-classic@3.6.0 None 0 761 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/theme-common@3.6.0 environment +1 468 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/theme-search-algolia@3.6.0 None 0 114 kB docusaurus-bot, fb, lex111, ...1 more
npm/@docusaurus/theme-translations@3.6.0 filesystem 0 335 kB slorber
npm/@mdx-js/react@3.1.0 None 0 14.4 kB wooorm
npm/@types/gtag.js@0.0.12 None 0 7.97 kB types
npm/@types/prismjs@1.26.5 None 0 19.4 kB types
npm/@types/react-router-dom@5.3.3 None 0 7.64 kB types
npm/@types/sax@1.2.7 None 0 6.97 kB types
npm/algoliasearch-helper@3.22.5 None 0 1.11 MB instantsearch-bot
npm/algoliasearch@4.24.0 None 0 210 kB shortcuts
npm/arg@5.0.2 None 0 13.7 kB leerobinson
npm/cheerio-select@2.1.0 None +1 287 kB feedic
npm/cheerio@1.0.0-rc.12 Transitive: network +4 1.09 MB feedic
npm/clsx@2.1.1 None 0 8.55 kB lukeed
npm/copy-text-to-clipboard@3.2.0 None 0 5.14 kB sindresorhus
npm/estree-util-visit@2.0.0 None 0 22.6 kB wooorm
npm/feed@4.2.2 None 0 105 kB jpmonette
npm/infima@0.2.0-alpha.45 None 0 620 kB slorber
npm/json-buffer@3.0.1 None 0 5.4 kB dominictarr
npm/nprogress@0.2.0 None 0 31.8 kB rstacruz
npm/p-try@2.2.0 None 0 4.37 kB sindresorhus
npm/parse-numeric-range@1.3.0 None 0 5.44 kB euank
npm/parse5-htmlparser2-tree-adapter@7.1.0 None 0 18.7 kB 43081j
npm/prism-react-renderer@2.4.0 None 0 738 kB formidablelabs
npm/prismjs@1.29.0 None 0 2.05 MB rundevelopment
npm/proto-list@1.2.4 None 0 4.86 kB isaacs
npm/react-dom@18.3.1 environment 0 4.51 MB react-bot
npm/react-json-view-lite@1.5.0 None 0 87.9 kB anyroad
npm/react@18.3.1 environment 0 318 kB react-bot
npm/reading-time@1.5.0 None 0 10.2 kB ngryman

🚮 Removed packages: npm/regenerator-runtime@0.14.1, npm/regenerator-transform@0.15.2, npm/regexpu-core@6.1.1, npm/registry-auth-token@5.0.2, npm/registry-url@6.0.1, npm/regjsgen@0.8.0, npm/regjsparser@0.11.2, npm/rehype-raw@7.0.0, npm/rehype-recma@1.0.0, npm/relateurl@0.2.7, npm/remark-directive@3.0.0, npm/remark-emoji@4.0.1, npm/remark-frontmatter@5.0.0, npm/remark-gfm@4.0.0, npm/remark-mdx@3.1.0, npm/remark-parse@11.0.0, npm/remark-rehype@11.1.1, npm/remark-stringify@11.0.0, npm/renderkid@3.0.0, npm/repeat-string@1.6.1, npm/require-from-string@2.0.2, npm/require-like@0.1.2, npm/requires-port@1.0.0, npm/resolve-alpn@1.2.1, npm/resolve-from@4.0.0, npm/resolve-pathname@3.0.0, npm/resolve@1.22.8, npm/responselike@3.0.0, npm/retry@0.13.1, npm/reusify@1.0.4, npm/rimraf@3.0.2, npm/rtl-detect@1.1.2, npm/run-parallel@1.2.0, npm/safe-buffer@5.2.1, npm/safer-buffer@2.1.2, npm/section-matter@1.0.0, npm/select-hose@2.0.0, npm/selfsigned@2.4.1, npm/semver-diff@4.0.0, npm/semver@7.6.3, npm/send@0.19.0, npm/serve-handler@6.1.6, npm/serve-index@1.9.1, npm/serve-static@1.16.2, npm/set-function-length@1.2.2, npm/setprototypeof@1.2.0, npm/shallow-clone@3.0.1, npm/shallowequal@1.1.0, npm/shebang-command@2.0.0, npm/shebang-regex@3.0.0, npm/shell-quote@1.8.1, npm/shelljs@0.8.5, npm/side-channel@1.0.6, npm/sirv@2.0.4, npm/sisteransi@1.0.5, npm/skin-tone@2.0.0, npm/slash@3.0.0, npm/snake-case@3.0.4, npm/sockjs@0.3.24, npm/sort-css-media-queries@2.2.0, npm/source-map-js@1.2.1, npm/source-map-support@0.5.21, npm/source-map@0.6.1, npm/space-separated-tokens@2.0.2, npm/spdy-transport@3.0.0, npm/spdy@4.0.2, npm/sprintf-js@1.0.3, npm/statuses@2.0.1, npm/std-env@3.7.0, npm/string-width@5.1.2, npm/string_decoder@1.3.0, npm/stringify-entities@4.0.4, npm/stringify-object@3.3.0, npm/strip-ansi@6.0.1, npm/strip-bom-string@1.0.0, npm/strip-final-newline@2.0.0, npm/strip-json-comments@2.0.1, npm/style-to-object@1.0.8, npm/stylehacks@6.1.1, npm/supports-color@7.2.0, npm/supports-preserve-symlinks-flag@1.0.0, npm/svg-parser@2.0.4, npm/terser-webpack-plugin@5.3.10, npm/text-table@0.2.0, npm/thunky@1.1.0, npm/tiny-invariant@1.3.3, npm/tiny-warning@1.0.3, npm/to-regex-range@5.0.1, npm/toidentifier@1.0.1, npm/totalist@3.0.1, npm/trim-lines@3.0.1, npm/trough@2.2.0, npm/tslib@2.8.1, npm/type-fest@2.19.0, npm/type-is@1.6.18, npm/typedarray-to-buffer@3.1.5, npm/undici-types@6.19.8, npm/unicode-canonical-property-names-ecmascript@2.0.1, npm/unicode-emoji-modifier-base@1.0.0, npm/unicode-match-property-ecmascript@2.0.0, npm/unicode-match-property-value-ecmascript@2.2.0, npm/unicode-property-aliases-ecmascript@2.1.0, npm/unique-string@3.0.0, npm/unist-util-is@6.0.0, npm/unist-util-position-from-estree@2.0.0, npm/unist-util-position@5.0.0, npm/unist-util-stringify-position@4.0.0, npm/unist-util-visit-parents@6.0.1, npm/unist-util-visit@5.0.0, npm/universalify@2.0.1, npm/update-browserslist-db@1.1.1, npm/update-notifier@6.0.2, npm/uri-js@4.4.1, npm/url-loader@4.1.1, npm/utila@0.4.0, npm/utility-types@3.11.0, npm/utils-merge@1.0.1, npm/uuid@8.3.2, npm/value-equal@1.0.1, npm/vary@1.1.2, npm/vfile-location@5.0.3, npm/vfile-message@4.0.2, npm/watchpack@2.4.2, npm/web-namespaces@2.0.1, npm/webpack-bundle-analyzer@4.10.2, npm/webpack-dev-middleware@5.3.4, npm/webpack-dev-server@4.15.2, npm/webpack-merge@6.0.1, npm/webpack-sources@3.2.3, npm/webpackbar@6.0.1, npm/websocket-extensions@0.1.4, npm/which@2.0.2, npm/widest-line@4.0.1, npm/wildcard@2.0.1, npm/wrap-ansi@8.1.0, npm/wrappy@1.0.2, npm/write-file-atomic@3.0.3, npm/ws@7.5.10, npm/yallist@3.1.1, npm/yaml@1.10.2, npm/yocto-queue@0.1.0, npm/zwitch@2.0.4

View full report↗︎

slorber commented 1 week ago

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[bot] commented 1 week ago

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

Build Status Details Updated (UTC)
default (Inspect) ✅ Auto-approved build - Nov 14, 2024, 12:32 PM
slorber commented 1 week ago

@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 commented 1 week ago

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 https://github.com/algolia/api-clients-automation/pull/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 commented 4 days ago

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.

CleanShot 2024-11-18 at 11 38 06@2x

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 🤔