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
{{ message }}
Repository navigation
Commit e24f3ab
Browse filesBrowse the repository at this point in the historyBrowse files
Restructure the README onto the house style shared by the other Nylas SDKs, and document the hook options, hook return values, and button props that were previously missing.
`@nylas/react` gives you Nylas Scheduler as React components, so you can drop a booking page or a full scheduling-page editor into your app instead of building availability logic, timezone handling, and booking forms yourself. It also ships a `useNylasConnect` hook and a `NylasConnectButton` for the OAuth flow that connects a user's calendar.
31
+
32
+
This repository is for contributors and anyone installing from source. If you just want to use the library in your app, head to the [**Scheduler guide**](https://developer.nylas.com/docs/v3/scheduler/) on developer.nylas.com.
11
33
12
-
## Installation
34
+
## Get started
13
35
14
-
Install Nylas React Components via npm:
36
+
1.[Sign up for a free Nylas account](https://dashboard-v3.nylas.com/register) and grab your client ID from the [Nylas Dashboard](https://dashboard-v3.nylas.com/).
37
+
2. Register your app's callback URI under **Hosted Authentication**, so the connection flow is allowed to run.
38
+
3. Install the package and render your first component — see below.
39
+
40
+
The [Scheduler quickstart](https://developer.nylas.com/docs/v3/getting-started/scheduler/) walks through a working setup end to end, with the finished code in [quickstart-scheduler-react](https://github.com/nylas-samples/quickstart-scheduler-react).
41
+
42
+
## ⚙️ Install
15
43
16
44
```bash
17
45
npm install @nylas/react@latest
46
+
# or
47
+
yarn add @nylas/react@latest
18
48
```
19
49
20
-
or yarn
50
+
### Requirements
51
+
52
+
-[Node.js](https://nodejs.org/en/) v20 or higher
53
+
-[React](https://react.dev/) 18 or 19
54
+
55
+
The package ships its own TypeScript types, and exposes three subpaths so you only bundle what you use:
56
+
57
+
| Import from | Contains |
58
+
| --- | --- |
59
+
|`@nylas/react`| Everything below except the Connect symbols |
60
+
|`@nylas/react/elements`| Scheduler and booking components |
61
+
|`@nylas/react/utils`|`NylasIdentityRequestWrapper`, and the `LANGUAGE_CODE` type |
62
+
|`@nylas/react/connect`|`useNylasConnect`, `NylasConnectButton`, and re-exports of `@nylas/connect`|
63
+
64
+
> **Note:**`useNylasConnect` and `NylasConnectButton` are available **only** from `@nylas/react/connect`, not from the package root.
- Import from `@nylas/react` or `@nylas/react/elements`
78
+
Three components are the entry points:
31
79
32
-
-**Connect**
33
-
-`useNylasConnect`, `NylasConnectButton`
34
-
- Import from `@nylas/react/connect`
80
+
-**`NylasScheduling`** — the booking page your end users see.
81
+
-**`NylasSchedulerEditor`** — the editor where your users build and configure scheduling pages.
82
+
-**`NylasSchedulingMethod`** — picks a scheduling method.
35
83
36
-
## Getting Started
84
+
Around 50 further components (`NylasAvailabilityPicker`, `NylasBookingForm`, `NylasBufferTime`, `NylasCancellationPolicy`, `NylasTimeslotPicker`, and so on) are exported as the building blocks those two compose, alongside `NylasNotetakerConfig` and a set of form primitives and icons. Most apps only need the entry points.
85
+
86
+
### Scheduler Editor
37
87
38
88
The following example adds the Nylas Scheduler Editor and Scheduling components to your React app.
39
89
40
90
> ⚠️ **Important:** Make sure to replace the `NYLAS_CLIENT_ID` with your Nylas Client ID. Your Nylas Client ID can be found in your app's Overview page on the [Nylas Dashboard](https://dashboard-v3.nylas.com).
To create a Scheduling Page from the Scheduler Editor, you'll need a working Scheduler UI. To do this, run a local server to host your Scheduler Editor and Scheduling Pages.
107
155
108
-
Navigate the root directory of your project and run the following command.
156
+
Navigate to the root directory of your project and run the following command.
109
157
110
158
```text
111
159
npm run dev -- --port <PORT>
112
160
```
113
161
114
162
After you run the command, open your browser to `http://localhost:<PORT>/scheduler-editor` to see your Scheduler Editor and create your first Scheduling Page.
115
163
116
-
117
-
## Nylas Connect Hook
164
+
### useNylasConnect hook
118
165
119
166
The `useNylasConnect` hook provides a simple way to add OAuth authentication to your React app using Nylas Connect.
`UseNylasConnectConfig` extends `ConnectConfig` from [`@nylas/connect`](https://github.com/nylas/javascript/tree/main/packages/nylas-connect), so every option there — `apiUrl`, `defaultScopes`, `persistTokens`, `logLevel`, `codeExchange`, `identityProviderToken`, and the rest — is accepted here too. The most common, plus the four the hook adds of its own:
153
197
154
198
| Option | Type | Default | Description |
155
-
|--------|------|---------|-------------|
156
-
| `clientId` | `string` | - | Your Nylas Client ID |
`unstyled` drops the default styling entirely; `cssVars` re-themes it without doing so, accepting `--nylas-btn-bg`, `--nylas-btn-fg`, `--nylas-btn-border`, and `--nylas-btn-bg-hover`.
279
+
280
+
### External identity providers
226
281
227
282
For applications that use external identity providers (via JWKS), you can pass identity provider tokens during authentication:
228
283
@@ -253,7 +308,9 @@ function App() {
253
308
}
254
309
```
255
310
256
-
### Custom Backend Code Exchange
311
+
Returning `null` continues without IDP claims; throwing fails authentication. Per-provider setup guides for Auth0, Clerk, Google, and WorkOS: [external identity providers](https://developer.nylas.com/docs/v3/auth/nylas-connect-react/use-external-idp/).
312
+
313
+
### Custom code exchange
257
314
258
315
For enhanced security, you can handle the OAuth code exchange on your backend:
259
316
@@ -309,12 +366,64 @@ function App() {
309
366
}
310
367
```
311
368
312
-
## Links
369
+
### Error handling
370
+
371
+
The hook surfaces failures on `error` rather than throwing, so render from it directly. `NylasConnectButton` reports them through `onError`, and `onCancel` fires separately when the user closes the popup.
if (error) return<p role="alert">Couldn't connect: {error.message}</p>;
377
+
```
378
+
379
+
Every error extends `NylasConnectError` and sets a distinct `name` — `PopupError` for a blocked or closed popup, `ConfigError` for a missing `clientId`, `OAuthError` when the provider rejects the request. All of them are re-exported from `@nylas/react/connect`.
380
+
381
+
## 💡 Examples
382
+
383
+
- [quickstart-scheduler-react](https://github.com/nylas-samples/quickstart-scheduler-react) — the finished code for the Scheduler quickstart.
384
+
- [nylas-samples](https://github.com/orgs/nylas-samples/repositories) — full sample apps and product quickstarts.
385
+
386
+
## 🤖 AI agents
387
+
388
+
[nylas/skills](https://github.com/nylas/skills) drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format:
389
+
390
+
```bash
391
+
npx skills add nylas/skills
392
+
/plugin marketplace add nylas/skills # Claude Code
See [`CHANGELOG.md`](CHANGELOG.md) for per-release notes.
410
+
411
+
## 💙 Contributing
412
+
413
+
Issues, ideas, and pull requests welcome — see [CONTRIBUTING.md](../../CONTRIBUTING.md). Before opening a large change, please open an issue or post in the [forum](https://forums.nylas.com) so we can sanity-check the direction.
414
+
415
+
## 🔒 Security
416
+
417
+
Found a vulnerability? Please **don't** open a publicissue. Report it through our [Vulnerability Disclosure Policy](https://www.nylas.com/security/vulnerability-disclosure-policy/).
418
+
419
+
## 🔗 Other Nylas SDKs
313
420
314
-
A complete walkthrough for setting up Scheduler can be found at [https://developer.nylas.com/docs/v3/getting-started/scheduler/](https://developer.nylas.com/docs/v3/getting-started/scheduler/), with the complete code available on [GitHub](https://github.com/nylas-samples/quickstart-scheduler-react).
0 commit comments