Skip to content

Commit 00fbcde

Browse files
authored
docs: add migration guide page (#449)
1 parent b1eed94 commit 00fbcde

File tree

6 files changed

+170
-11
lines changed

6 files changed

+170
-11
lines changed

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
"scripts:test": "yarn workspace scripts test",
3030
"specs:fix": "eslint --ext=yml specs/$0 --fix",
3131
"specs:lint": "eslint --ext=yml specs/$0",
32-
"website": "yarn workspace website start --host 0.0.0.0",
32+
"website": "BUNDLE_WITH_DOC=true DOCKER=true yarn cli build specs all && yarn workspace website start --host 0.0.0.0",
3333
"website:build": "yarn workspace website build"
3434
},
3535
"devDependencies": {

website/docs/api-clients/getting-started.mdx renamed to website/docs/api-clients/installation.mdx

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Getting Started
2+
title: Installation
33
---
44

55
import Tabs from '@theme/Tabs';
@@ -14,18 +14,22 @@ import TabItem from '@theme/TabItem';
1414
}>
1515
<TabItem value="js">
1616

17-
## Installation
18-
1917
To get started, you first need to install `algoliasearch` (or any other available API client package). You can find the full list of available packages [here](https://www.npmjs.com/org/experimental-api-clients-automation).
2018

19+
All of our clients comes with type definition, and are available for both `browser` and `node` environments.
20+
2121
```bash
2222
yarn add @experimental-api-clients-automation/algoliasearch
23+
# or
24+
npm install @experimental-api-clients-automation/algoliasearch
2325
```
2426

2527
Or use a specific package:
2628

2729
```bash
2830
yarn add @experimental-api-clients-automation/client-search
31+
# or
32+
npm install @experimental-api-clients-automation/client-search
2933
```
3034

3135
**Without a package manager**
@@ -47,7 +51,7 @@ const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
4751

4852
// And access analytics or personalization client
4953
const analyticsClient = client.initAnalytics('<YOUR_APP_ID>', '<YOUR_API_KEY>');
50-
const personalizationCilent = client.initPersonalization(
54+
const personalizationClient = client.initPersonalization(
5155
'<YOUR_APP_ID>',
5256
'<YOUR_API_KEY>',
5357
'eu'

website/docs/api-clients/introduction.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Introduction
44

55
# Introduction
66

7-
This section hosts informations about the [API clients automation](https://github.com/algolia/api-clients-automation) repository. For informations regarding the clients usage, see [the clients page](/docs/api-clients/introduction).
7+
This section hosts informations about the [usage of the API clients](https://github.com/algolia/api-clients-automation). For informations regarding the automation and how to contribute, see [the automation page](/docs/automation/introduction).
88

99
## Repositories
1010

@@ -16,7 +16,7 @@ Generated code in production can be find on repository of the clients.
1616

1717
## Usage
1818

19-
See [the getting started](/docs/api-clients/getting-started) page.
19+
See [the installation](/docs/api-clients/installation) page.
2020

2121
You can also check the [playground](/docs/automation/testing/playground) if you'd like to test clients locally.
2222

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Migration guide
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
This document lists every known breaking change, not all of them may affect your application.
9+
10+
:::caution
11+
12+
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/)
13+
14+
**You should thoroughly test your application once the migration is over.**
15+
16+
:::
17+
18+
## Common breaking changes
19+
20+
The changes below are effective on all of the API clients.
21+
22+
| Previous | Latest | Description |
23+
| ----------- | :---------- | :------------------------------------------------- |
24+
| `initIndex` | **removed** | All methods are now available at the client level. |
25+
26+
## API Client specific breaking changes
27+
28+
The changes below are effective on the selected API client.
29+
30+
For informations regarding the installation of the package, please see [the installation page](/docs/api-clients/installation)
31+
32+
<Tabs
33+
groupId="language"
34+
defaultValue="js"
35+
values={[
36+
{ label: 'JavaScript', value: 'js', }
37+
]
38+
}>
39+
<TabItem value="js">
40+
41+
| Previous | Latest | Description |
42+
| -------------------- | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43+
| `@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). |
44+
| `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). |
45+
| `search` | `searchClient` | Exported clients are suffixed by `Client`. |
46+
47+
</TabItem>
48+
</Tabs>
49+
50+
### Installation
51+
52+
<Tabs
53+
groupId="language"
54+
defaultValue="js"
55+
values={[
56+
{ label: 'JavaScript', value: 'js', }
57+
]
58+
}>
59+
<TabItem value="js">
60+
61+
To get started, first install the `algoliasearch` client.
62+
63+
```bash
64+
yarn add @experimental-api-clients-automation/algoliasearch
65+
# or
66+
npm install @experimental-api-clients-automation/algoliasearch
67+
```
68+
69+
You can now uninstall the previously added client.
70+
71+
> Make sure to update all your imports.
72+
73+
```bash
74+
yarn remove algoliasearch
75+
# or
76+
npm uninstall algoliasearch
77+
```
78+
79+
You can continue this guide on [our installation page](/docs/api-clients/installation).
80+
81+
</TabItem>
82+
</Tabs>
83+
84+
### Importing algoliasearch using ES Modules
85+
86+
<Tabs
87+
groupId="language"
88+
defaultValue="js"
89+
values={[
90+
{ label: 'JavaScript', value: 'js', }
91+
]
92+
}>
93+
<TabItem value="js">
94+
95+
```diff
96+
- import algoliasearch from 'algoliasearch/lite';
97+
+ import { algoliasearchLiteClient } from '@experimental-api-clients-automation/algoliasearch-lite';
98+
99+
- import algoliasearch from 'algoliasearch';
100+
+ import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
101+
```
102+
103+
</TabItem>
104+
</Tabs>
105+
106+
### Methods targetting an `indexName`
107+
108+
<Tabs
109+
groupId="language"
110+
defaultValue="js"
111+
values={[
112+
{ label: 'JavaScript', value: 'js', }
113+
]
114+
}>
115+
<TabItem value="js">
116+
117+
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.
118+
119+
```js
120+
import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
121+
122+
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
123+
124+
// only query string
125+
const searchResults = await client.search({
126+
indexName: '<YOUR_INDEX_NAME>',
127+
searchParams: { query: 'myQuery' },
128+
});
129+
130+
// with params
131+
const searchResults2 = await client.search({
132+
indexName: '<YOUR_INDEX_NAME>',
133+
searchParams: {
134+
query: 'myQuery',
135+
attributesToRetrieve: ['firstname', 'lastname'],
136+
hitsPerPage: 50,
137+
},
138+
});
139+
```
140+
141+
</TabItem>
142+
</Tabs>

website/sidebars.js

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,15 @@ const sidebars = {
4545
},
4646
],
4747
// Everything related to the generated clients usage
48-
clients: ['api-clients/introduction', 'api-clients/getting-started'],
48+
clients: [
49+
'api-clients/introduction',
50+
{
51+
type: 'category',
52+
label: 'Getting Started',
53+
collapsed: false,
54+
items: ['api-clients/installation', 'api-clients/migration-guide'],
55+
},
56+
],
4957
};
5058

5159
// eslint-disable-next-line import/no-commonjs

website/src/css/custom.css

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@
55
--ifm-color-primary: #5468ff;
66
--ifm-footer-background-color: #f5f5fa;
77
--ifm-menu-color-background-active: var(--ifm-color-emphasis-200);
8-
--ifm-font-family-monospace: Open Sans,system-ui,BlinkMacSystemFont,-apple-system,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;
9-
--ifm-font-family-base: Open Sans,system-ui,BlinkMacSystemFont,-apple-system,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;
8+
--ifm-font-family-base: Open Sans, system-ui, BlinkMacSystemFont,
9+
-apple-system, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Fira Sans,
10+
Droid Sans, Helvetica Neue, sans-serif;
1011
}
1112

1213
html[data-theme='dark'] {
@@ -51,8 +52,12 @@ html[data-theme='dark'] .header-github-link:before {
5152
}
5253

5354
/* Font */
54-
@import url("https://fonts.googleapis.com/css?family=Open+Sans");
55+
@import url('https://fonts.googleapis.com/css?family=Open+Sans');
5556

57+
/* override italic keywords in code blocks */
58+
code .token.keyword {
59+
font-style: normal !important;
60+
}
5661

5762
/* Redoc fix */
5863
.redocusaurus .menu-content label.-depth0 {

0 commit comments

Comments
 (0)