-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add migration guide page (#449)
- Loading branch information
Showing
6 changed files
with
170 additions
and
11 deletions.
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.** | ||
|
|
||
| ::: | ||
|
|
||
| ## 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. | | ||
|
|
||
| ## 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'; | ||
| ``` | ||
|
|
||
| </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