You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+18-16Lines changed: 18 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,24 +2,26 @@
2
2
3
3
This library makes it easy to use the [TalkJS](https://talkjs.com) pre-built chat UIs inside a React web application.
4
4
5
-
`talkjs-react` encapsulates `talkjs`, the framework-independent ("vanilla") [TalkJS JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK). It only provides React components for UI-related matters: For anything related to data manipulation, such as synchronizing user data, or creating and joining conversations, use the vanilla SDK.
5
+
`@talkjs/react` encapsulates `talkjs`, the framework-independent ("vanilla") [TalkJS JavaScript SDK](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK). It only provides React components for UI-related matters: For anything related to data manipulation, such as synchronizing user data, or creating and joining conversations, use the vanilla SDK.
6
6
7
7
TypeScript bindings are included.
8
8
9
9
## Experimental note
10
10
This library is hot off the press. It provides a substantially faster way to get TalkJS going with React, but it may still have a few childhood quirks.
11
11
12
-
If you encounter any problems with `talkjs-react`, please open an issue. If you have a problem with TalkJS itself, or if you're not sure where the problem lies, it's better to open a chat with our support on https://talkjs.com/ (just open the chat widget). TalkJS support is staffed by engineers.
12
+
If you encounter any problems with `@talkjs/react`, please open an issue. If you have a problem with TalkJS itself, or if you're not sure where the problem lies, it's better to open a chat with our support on https://talkjs.com/ (just open the chat widget). TalkJS support is staffed by engineers.
13
13
14
14
## Getting Started
15
15
16
-
Install both `talkjs-react` and the vanilla [TalkJS NPM package](https://www.npmjs.com/package/talkjs):
16
+
Install both `@talkjs/react` and the vanilla [TalkJS NPM package](https://www.npmjs.com/package/talkjs):
17
17
18
18
```sh
19
-
yarn add talkjs talkjs-react
19
+
npm install talkjs @talkjs/react
20
+
# or
21
+
yarn add talkjs @talkjs/react
20
22
```
21
23
22
-
`talkjs-react` is just a thin wrapper around `talkjs`. Notably, it is designed such that when you update to a new version of `talkjs` that exposes new options, methods or events, you can use these right away from the React components, without having to update `talkjs-react` (or wait for such an update to be published)
24
+
`@talkjs/react` is just a thin wrapper around `talkjs`. Notably, it is designed such that when you update to a new version of `talkjs` that exposes new options, methods or events, you can use these right away from the React components, without having to update `@talkjs/react` (or wait for such an update to be published)
23
25
24
26
## Load a UI for existing chat data
25
27
@@ -28,7 +30,7 @@ yarn add talkjs talkjs-react
28
30
Wrap your main app components in a session:
29
31
30
32
```tsx
31
-
import { Session } from"talkjs-react";
33
+
import { Session } from"@talkjs/react";
32
34
33
35
//...
34
36
@@ -46,7 +48,7 @@ The session encapsulates a connection to the TalkJS realtime infrastructure, and
46
48
Anywhere inside the children of `<Session>` you can create a `<Chatbox>`, an `<Inbox>` or a `<Popup>`:
47
49
48
50
```tsx
49
-
import { Chatbox } from"talkjs-react";
51
+
import { Chatbox } from"@talkjs/react";
50
52
51
53
//...
52
54
@@ -73,7 +75,7 @@ To create or update user data, just replace the `userId` prop by `syncUser`. Thi
73
75
74
76
```tsx
75
77
import { useCallback } from"react";
76
-
import { Session } from"talkjs-react";
78
+
import { Session } from"@talkjs/react";
77
79
importTalkfrom"talkjs";
78
80
79
81
//...
@@ -98,7 +100,7 @@ const syncUser = useCallback(
98
100
</Session>;
99
101
```
100
102
101
-
Note: you can't create `Talk.User` object before the TalkJS SDK has initialized. In vanilla JS you'd have to await `Talk.ready` promise for this, but `talkjs-react` ensures that you`syncUser` callback is only called after TalkJS is ready.
103
+
Note: you can't create `Talk.User` object before the TalkJS SDK has initialized. In vanilla JS you'd have to await `Talk.ready` promise for this, but `@talkjs/react` ensures that your`syncUser` callback is only called after TalkJS is ready.
102
104
103
105
### 2. Create and join a conversation
104
106
@@ -108,7 +110,7 @@ Just replace the `conversation` prop by a `syncConversation` callback, which wil
108
110
109
111
```tsx
110
112
import { useCallback } from"react";
111
-
import { Chatbox } from"talkjs-react";
113
+
import { Chatbox } from"@talkjs/react";
112
114
importTalkfrom"talkjs";
113
115
114
116
//...
@@ -194,7 +196,7 @@ If you need to do things with your
194
196
In any child component of `<Session>` you can call the `useSession` hook to get the `Talk.Session` object:
@@ -213,7 +215,7 @@ since been destroyed. See the section on liveness below.
213
215
### Using refs
214
216
215
217
216
-
All `talkjs-react` components let you assign the underlying TalkJS object to a
218
+
All `@talkjs/react` components let you assign the underlying TalkJS object to a
217
219
ref:
218
220
219
221
```tsx
@@ -293,12 +295,12 @@ Should you want to contribute, please take note of the design notes below.
293
295
294
296
## Design notes
295
297
296
-
This library has been designed to be maximally forward-compatible with future TalkJS features. The `talkjs` package is a peer dependency, not a direct dependency, which means you can control which TalkJS version you want to be on. It also means you won't need to wait for a new version of `talkjs-react` to be published before you can get access to new TalkJS features.
298
+
This library has been designed to be maximally forward-compatible with future TalkJS features. The `talkjs` package is a peer dependency, not a direct dependency, which means you can control which TalkJS version you want to be on. It also means you won't need to wait for a new version of `@talkjs/react` to be published before you can get access to new TalkJS features.
297
299
298
-
From our (TalkJS) perspective, it means we have a lower maintenance burden: we can ship new JS features without having to update (and test and verify) `talkjs-react`.
300
+
From our (TalkJS) perspective, it means we have a lower maintenance burden: we can ship new JS features without having to update (and test and verify) `@talkjs/react`.
299
301
300
302
This works because vanilla TalkJS is fully backward compatible and has a very consistent design: all UI components are instantiated and mutated in the same way. The React components simply treats any prop that looks like an event (name starts with "on") like an event. Also, barring some props unique to the react components (such as `syncConversation`, `style` and `loadingComponent`), all remaining props are simply assumed to be valid options to pass to `createChatbox` and its sister methods.
301
303
302
-
This way, if TalkJS eg adds support for a new event or a new option, this will Just Work without updating `talkjs-react`. Modern TypeScript features (notably, [template literal types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)) let us do this in a fully type-safe manner: If you upgrade `talkjs`, then your invocations to `talkjs-react` components will allow new props.
304
+
This way, if TalkJS eg adds support for a new event or a new option, this will Just Work without updating `@talkjs/react`. Modern TypeScript features (notably, [template literal types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)) let us do this in a fully type-safe manner: If you upgrade `talkjs`, then your invocations to `@talkjs/react` components will allow new props.
303
305
304
-
Any future changes should follow this same design: they should be maximally forward compatible.
306
+
Any future changes should follow this same design: they should be maximally forward compatible.
0 commit comments