docs: add migration guide page #449
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| --- | ||
| title: Migration guide | ||
| --- | ||
|
|
||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| This document lists every known breaking change, not all of them may affect your application. | ||
|
|
||
| :::caution | ||
|
|
||
| The amount of changes in this new version is significant. If you were using a version older than v4, please also read [this migration guide](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/javascript/) | ||
|
|
||
| **You should thoroughly test your application once the migration is over.** | ||
|
There was a problem hiding this comment. Not sure if we need this line. It's kind of obvious. Also, it's not that we're providing any special tool or guide to test things 🤔 There was a problem hiding this comment. Yep I agree it's not that mandatory, but I feel like it's still good to mention it so we don't get people saying their prod is broken after upgrade :D |
||
|
|
||
| ::: | ||
|
|
||
| ## Common breaking changes | ||
|
|
||
| The changes below are effective on all of the API clients. | ||
|
|
||
| | Previous | Latest | Description | | ||
| | ----------- | :---------- | :------------------------------------------------- | | ||
| | `initIndex` | **removed** | All methods are now available at the client level. | | ||
|
There was a problem hiding this comment. Do we have any example to work around this somewhere else? If not, we should add an example here, to actually explain what it means to them, and what they need to do to migrate. edit: I just found "Methods targetting an There was a problem hiding this comment. Ah yep indeed I'll link it! |
||
|
|
||
| ## API Client specific breaking changes | ||
|
|
||
| The changes below are effective on the selected API client. | ||
|
|
||
| For informations regarding the installation of the package, please see [the installation page](/docs/api-clients/installation) | ||
|
|
||
| <Tabs | ||
| groupId="language" | ||
| defaultValue="js" | ||
| values={[ | ||
| { label: 'JavaScript', value: 'js', } | ||
| ] | ||
| }> | ||
| <TabItem value="js"> | ||
|
|
||
| | Previous | Latest | Description | | ||
| | -------------------- | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `@algolia` | `@experimental-api-clients-automation` | **During the beta phase**, the clients are available under the NPM `@experimental-api-clients-automation` namespace, you can find a full list [here](https://www.npmjs.com/org/experimental-api-clients-automation). | | ||
| | `algoliasearch/lite` | `algoliasearch-lite` | The lite version of the client now have [its own package](https://www.npmjs.com/package/@experimental-api-clients-automation/algoliasearch-lite). | | ||
| | `search` | `searchClient` | Exported clients are suffixed by `Client`. | | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ### Installation | ||
|
|
||
| <Tabs | ||
| groupId="language" | ||
| defaultValue="js" | ||
| values={[ | ||
| { label: 'JavaScript', value: 'js', } | ||
| ] | ||
| }> | ||
| <TabItem value="js"> | ||
|
|
||
| To get started, first install the `algoliasearch` client. | ||
|
|
||
| ```bash | ||
| yarn add @experimental-api-clients-automation/algoliasearch | ||
| # or | ||
| npm install @experimental-api-clients-automation/algoliasearch | ||
| ``` | ||
|
|
||
| You can now uninstall the previously added client. | ||
|
|
||
| > Make sure to update all your imports. | ||
|
|
||
| ```bash | ||
| yarn remove algoliasearch | ||
| # or | ||
| npm uninstall algoliasearch | ||
| ``` | ||
|
|
||
| You can continue this guide on [our installation page](/docs/api-clients/installation). | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ### Importing algoliasearch using ES Modules | ||
|
|
||
| <Tabs | ||
| groupId="language" | ||
| defaultValue="js" | ||
| values={[ | ||
| { label: 'JavaScript', value: 'js', } | ||
| ] | ||
| }> | ||
| <TabItem value="js"> | ||
|
|
||
| ```diff | ||
| - import algoliasearch from 'algoliasearch/lite'; | ||
| + import { algoliasearchLiteClient } from '@experimental-api-clients-automation/algoliasearch-lite'; | ||
|
|
||
| - import algoliasearch from 'algoliasearch'; | ||
| + import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch'; | ||
|
Comment on lines
+96
to
+100
There was a problem hiding this comment. Very readable with diff! Btw, it's a side note, but it's a bit inconsistent to me that we have There was a problem hiding this comment. Yep definitely, the only thing is that since it's generated, it adds the So either we make There was a problem hiding this comment. Hah, I don't like the latter either! Let's leave it as-is, and think about it later :) |
||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ### Methods targetting an `indexName` | ||
|
|
||
| <Tabs | ||
| groupId="language" | ||
| defaultValue="js" | ||
| values={[ | ||
| { label: 'JavaScript', value: 'js', } | ||
| ] | ||
| }> | ||
| <TabItem value="js"> | ||
|
|
||
| Prior to the `initIndex` removal stated in the [Common breaking changes](#common-breaking-changes), all methods previously available at the `initIndex` level requires the `indexName` to be sent with the query. | ||
|
|
||
| ```js | ||
| import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch'; | ||
|
|
||
| const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>'); | ||
|
|
||
| // only query string | ||
| const searchResults = await client.search({ | ||
| indexName: '<YOUR_INDEX_NAME>', | ||
| searchParams: { query: 'myQuery' }, | ||
| }); | ||
|
|
||
| // with params | ||
| const searchResults2 = await client.search({ | ||
| indexName: '<YOUR_INDEX_NAME>', | ||
| searchParams: { | ||
| query: 'myQuery', | ||
| attributesToRetrieve: ['firstname', 'lastname'], | ||
| hitsPerPage: 50, | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As our docs become bigger, is there a way to split those files per languages ? It's not urgent at all
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep it would make us duplicate content, however I think we could read the snippets from an external file and inject it here, since it's JS
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we know in the end that it will most likely live in the official doc I don't think we should dedicate time for that but it's definitely doable