From e72ae39b5f60e5bdfc38481c1f5160441d7c4ae5 Mon Sep 17 00:00:00 2001 From: Nick Barraclough Date: Tue, 1 Sep 2026 09:46:39 -0500 Subject: [PATCH 1/3] fix(@nylas/react): correct Connect import paths in README `useNylasConnect` and `NylasConnectButton` are exported only from the `@nylas/react/connect` subpath. `src/index.ts` re-exports `./elements` and `./utils`, neither of which reaches them, so the four README snippets importing from `@nylas/react` could not resolve. Also corrects the Exports overview, which claimed the Connect symbols were importable from `@nylas/react` as well as `@nylas/react/connect`. The Elements entries are unaffected: `NylasSchedulerEditor` and `NylasScheduling` genuinely resolve from the package root. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/fix-react-readme-connect-imports.md | 5 +++++ packages/react/README.md | 10 +++++----- 2 files changed, 10 insertions(+), 5 deletions(-) create mode 100644 .changeset/fix-react-readme-connect-imports.md diff --git a/.changeset/fix-react-readme-connect-imports.md b/.changeset/fix-react-readme-connect-imports.md new file mode 100644 index 0000000..f541c99 --- /dev/null +++ b/.changeset/fix-react-readme-connect-imports.md @@ -0,0 +1,5 @@ +--- +"@nylas/react": patch +--- + +Fix the import path in the README's Connect examples. `useNylasConnect` and `NylasConnectButton` are only exported from the `@nylas/react/connect` subpath, so the snippets that imported them from `@nylas/react` could not resolve. diff --git a/packages/react/README.md b/packages/react/README.md index a91ddd0..777e151 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -31,7 +31,7 @@ or yarn - **Connect** - `useNylasConnect`, `NylasConnectButton` - - Import from `@nylas/react` or `@nylas/react/connect` + - Import from `@nylas/react/connect` ## Getting Started @@ -121,7 +121,7 @@ The `useNylasConnect` hook provides a simple way to add OAuth authentication to ### Basic Usage ```jsx -import { useNylasConnect } from '@nylas/react'; +import { useNylasConnect } from "@nylas/react/connect"; function LoginButton() { const { isConnected, connect, logout, grant, isLoading } = useNylasConnect({ @@ -204,7 +204,7 @@ The `NylasConnectButton` component provides a simple way to add email provider a ### Basic Usage ```jsx -import { NylasConnectButton } from "@nylas/react"; +import { NylasConnectButton } from "@nylas/react/connect"; function App() { return ( @@ -227,7 +227,7 @@ function App() { For applications that use external identity providers (via JWKS), you can pass identity provider tokens during authentication: ```jsx -import { NylasConnectButton } from "@nylas/react"; +import { NylasConnectButton } from "@nylas/react/connect"; function App() { // Function to retrieve JWT token from your external identity provider @@ -258,7 +258,7 @@ function App() { For enhanced security, you can handle the OAuth code exchange on your backend: ```jsx -import { NylasConnectButton } from "@nylas/react"; +import { NylasConnectButton } from "@nylas/react/connect"; function App() { const handleCodeExchange = async (params) => { From 5ab61c886c6d71102688acc79f236aa06e54c971 Mon Sep 17 00:00:00 2001 From: Nick Barraclough Date: Tue, 1 Sep 2026 10:06:42 -0500 Subject: [PATCH 2/3] docs(@nylas/react): restructure README onto the SDK house style Brings the README onto the section skeleton shared by @nylas/connect, nylas-nodejs, nylas-python, nylas-ruby and nylas-java: centered header block with banner, tagline, badge row and nav links, then Get started, Install, Usage, Examples, AI agents, Reference, Upgrading, Contributing, Security, Other Nylas SDKs, License. All existing prose and every code sample are preserved. The Scheduler Editor example, the local dev server instructions, the hook usage, the environment setup, the identity provider example and the custom code exchange example are unchanged apart from being moved under `## Usage`. Documentation gaps closed while restructuring: - The Exports overview listed 3 of the ~59 exported components without saying what the rest were. Now names the 3 entry points and explains that the others are their building blocks. - The hook config table omitted `initialLoadingState`, and did not mention that UseNylasConnectConfig extends ConnectConfig. - The hook return values omitted `setLogLevel` and `connectClient`. - NylasConnectButton had no prop documentation at all; 26 props are now grouped by purpose, including the `unstyled` and `cssVars` theming hooks. - CHANGELOG.md and LICENSE.md exist in the package but were never linked. Both now are. - Added an Error handling section, absent entirely. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/react-readme-house-style.md | 5 + packages/react/README.md | 240 ++++++++++++++++++------- 2 files changed, 179 insertions(+), 66 deletions(-) create mode 100644 .changeset/react-readme-house-style.md diff --git a/.changeset/react-readme-house-style.md b/.changeset/react-readme-house-style.md new file mode 100644 index 0000000..d314685 --- /dev/null +++ b/.changeset/react-readme-house-style.md @@ -0,0 +1,5 @@ +--- +"@nylas/react": patch +--- + +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. diff --git a/packages/react/README.md b/packages/react/README.md index 777e151..cd1f70c 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,46 +1,93 @@ -# Nylas React Components +
+ + Nylas + -React components for Nylas Scheduler +

Nylas React Components

-![npm](https://img.shields.io/npm/v/@nylas/react) +

+ Scheduler components and OAuth connection hooks for React +

-## Requirements +

+ npm version + downloads + TypeScript + license +

-- [Node.js](https://nodejs.org/en/) v20 or higher -- [React.js](https://react.dev/) v18 or higher +

+ ๐Ÿ“– Scheduler guide ยท + ๐Ÿ“š API Reference ยท + ๐Ÿš€ Sign up ยท + ๐Ÿ’ก Samples ยท + ๐Ÿ’ฌ Forum +

+
+ +
+ +`@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. + +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. -## Installation +## Get started -Install Nylas React Components via npm: +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/). +2. Register your app's callback URI under **Hosted Authentication**, so the connection flow is allowed to run. +3. Install the package and render your first component โ€” see below. + +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). + +## โš™๏ธ Install ```bash npm install @nylas/react@latest +# or +yarn add @nylas/react@latest ``` -or yarn +### Requirements + +- [Node.js](https://nodejs.org/en/) v20 or higher +- [React](https://react.dev/) 18 or 19 + +The package ships its own TypeScript types, and exposes three subpaths so you only bundle what you use: + +| Import from | Contains | +| --- | --- | +| `@nylas/react` | Everything below except the Connect symbols | +| `@nylas/react/elements` | Scheduler and booking components | +| `@nylas/react/connect` | `useNylasConnect`, `NylasConnectButton`, and re-exports of `@nylas/connect` | + +> **Note:** `useNylasConnect` and `NylasConnectButton` are available **only** from `@nylas/react/connect`, not from the package root. + +To install from source: ```bash - yarn add @nylas/react@latest +git clone https://github.com/nylas/javascript.git +cd javascript +pnpm install ``` -## Exports overview +## โšก๏ธ Usage + +### Scheduler components -- **Elements** - - `NylasSchedulerEditor`, `NylasScheduling`, `NylasSchedulingMethod` - - Import from `@nylas/react` or `@nylas/react/elements` +Three components are the entry points: -- **Connect** - - `useNylasConnect`, `NylasConnectButton` - - Import from `@nylas/react/connect` +- **`NylasScheduling`** โ€” the booking page your end users see. +- **`NylasSchedulerEditor`** โ€” the editor where your users build and configure scheduling pages. +- **`NylasSchedulingMethod`** โ€” picks a scheduling method. -## Getting Started +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. + +### Scheduler Editor The following example adds the Nylas Scheduler Editor and Scheduling components to your React app. > โš ๏ธ **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). -### Adding the Components - ```jsx import { BrowserRouter, Route, Routes } from "react-router-dom"; import { NylasSchedulerEditor, NylasScheduling } from "@nylas/react"; @@ -101,11 +148,11 @@ function App() { export default App; ``` -### Start a local development server +### Local development server 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. -Navigate the root directory of your project and run the following command. +Navigate to the root directory of your project and run the following command. ```text npm run dev -- --port @@ -113,20 +160,17 @@ npm run dev -- --port After you run the command, open your browser to `http://localhost:/scheduler-editor` to see your Scheduler Editor and create your first Scheduling Page. - -## Nylas Connect Hook +### useNylasConnect hook The `useNylasConnect` hook provides a simple way to add OAuth authentication to your React app using Nylas Connect. -### Basic Usage - ```jsx import { useNylasConnect } from "@nylas/react/connect"; function LoginButton() { const { isConnected, connect, logout, grant, isLoading } = useNylasConnect({ - clientId: 'your-nylas-client-id', - redirectUri: 'http://localhost:3000/callback' + clientId: "your-nylas-client-id", + redirectUri: "http://localhost:3000/callback", }); if (isLoading) return
Loading...
; @@ -141,42 +185,45 @@ function LoginButton() { } return ( - + ); } ``` +#### Configuration -### Configuration +`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: | Option | Type | Default | Description | -|--------|------|---------|-------------| -| `clientId` | `string` | - | Your Nylas Client ID | -| `redirectUri` | `string` | - | OAuth callback URL | -| `autoHandleCallback` | `boolean` | `true` | Automatically handle OAuth callback | -| `autoRefreshInterval` | `number` | - | Auto-refresh session interval (ms) | -| `retryAttempts` | `number` | `0` | Number of retry attempts for failed operations | -| `enableAutoRecovery` | `boolean` | `false` | Enable automatic error recovery | +| --- | --- | --- | --- | +| `clientId` | `string` | `NYLAS_CLIENT_ID` | Your Nylas Client ID | +| `redirectUri` | `string` | `NYLAS_REDIRECT_URI` | OAuth callback URL | +| `autoHandleCallback` | `boolean` | `true` | Automatically handle the OAuth callback | +| `autoRefreshInterval` | `number` | disabled | Auto-refresh session interval, in ms | +| `initialLoadingState` | `boolean` | `true` | Loading state the hook mounts with | +| `retryAttempts` | `number` | `0` | Retry attempts for failed operations | +| `enableAutoRecovery` | `boolean` | `false` | Automatic recovery from network errors | -### Hook Return Values - -The hook returns an object with the following properties: +#### Return values **State:** -- `isConnected` - Whether user is authenticated -- `grant` - Current user's grant information -- `isLoading` - Loading state for operations -- `error` - Current error, if any + +- `isConnected` โ€” whether the user is authenticated +- `grant` โ€” the current user's `GrantInfo`, or `null` +- `isLoading` โ€” loading state for operations +- `error` โ€” current error, if any **Actions:** -- `connect(options)` - Start OAuth flow -- `logout(grantId?)` - Sign out user -- `refreshSession()` - Refresh current session -- `subscribe(callback)` - Listen to connection events -### Environment Setup +- `connect(options)` โ€” start the OAuth flow +- `logout(grantId?)` โ€” sign the user out +- `refreshSession()` โ€” refresh the current session +- `subscribe(callback)` โ€” listen to connection events +- `setLogLevel(level)` โ€” change log verbosity at runtime + +The underlying client is also returned as `connectClient`, for anything the hook doesn't wrap. + +#### Environment setup For security, use environment variables for your configuration: @@ -189,20 +236,16 @@ VITE_NYLAS_REDIRECT_URI=http://localhost:3000/callback ```jsx const { isConnected, connect } = useNylasConnect({ clientId: import.meta.env.VITE_NYLAS_CLIENT_ID, - redirectUri: import.meta.env.VITE_NYLAS_REDIRECT_URI + redirectUri: import.meta.env.VITE_NYLAS_REDIRECT_URI, }); ``` +Next.js uses `NEXT_PUBLIC_` instead of `VITE_`. - - - -## Nylas Connect Button +### NylasConnectButton The `NylasConnectButton` component provides a simple way to add email provider authentication to your React application. -### Basic Usage - ```jsx import { NylasConnectButton } from "@nylas/react/connect"; @@ -222,7 +265,18 @@ function App() { } ``` -### External Identity Provider Integration +Beyond `clientId` and `redirectUri`, the props fall into four groups: + +| Group | Props | +| --- | --- | +| Connection | `apiUrl`, `defaultScopes`, `persistTokens`, `method`, `provider`, `scopes`, `loginHint`, `popupWidth`, `popupHeight` | +| Appearance | `text`, `children`, `variant` (`primary` \| `outline`), `size` (`sm` \| `md` \| `lg`), `className`, `style`, `disabled`, `unstyled`, `cssVars` | +| Callbacks | `onStart`, `onSuccess`, `onError`, `onCancel` | +| Advanced | `identityProviderToken`, `codeExchange` | + +`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`. + +### External identity providers For applications that use external identity providers (via JWKS), you can pass identity provider tokens during authentication: @@ -253,7 +307,9 @@ function App() { } ``` -### Custom Backend Code Exchange +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/). + +### Custom code exchange For enhanced security, you can handle the OAuth code exchange on your backend: @@ -309,12 +365,64 @@ function App() { } ``` -## Links +### Error handling + +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. + +```jsx +const { error, connect } = useNylasConnect({ clientId, redirectUri }); + +if (error) return

Couldn't connect: {error.message}

; +``` + +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`. + +## ๐Ÿ’ก Examples + +- [quickstart-scheduler-react](https://github.com/nylas-samples/quickstart-scheduler-react) โ€” the finished code for the Scheduler quickstart. +- [nylas-samples](https://github.com/orgs/nylas-samples/repositories) โ€” full sample apps and product quickstarts. + +## ๐Ÿค– AI agents + +[nylas/skills](https://github.com/nylas/skills) drops Nylas into Claude Code, Cursor, Codex, and other agents that support the skills format: + +```bash +npx skills add nylas/skills +/plugin marketplace add nylas/skills # Claude Code +``` + +## ๐Ÿ“š Reference + +- **Scheduler guide:** [developer.nylas.com/docs/v3/scheduler](https://developer.nylas.com/docs/v3/scheduler/) +- **Scheduler quickstart:** [developer.nylas.com/docs/v3/getting-started/scheduler](https://developer.nylas.com/docs/v3/getting-started/scheduler/) +- **Scheduler API reference:** [developer.nylas.com/docs/api/v3/scheduler](https://developer.nylas.com/docs/api/v3/scheduler/) +- **React connect guide:** [developer.nylas.com/docs/v3/auth/nylas-connect-react](https://developer.nylas.com/docs/v3/auth/nylas-connect-react/) +- **`useNylasConnect` reference:** [every option and return value](https://developer.nylas.com/docs/v3/auth/nylas-connect-react/usenylasconnect/) +- **`NylasConnectButton` reference:** [every prop](https://developer.nylas.com/docs/v3/auth/nylas-connect-react/nylasconnectbutton/) +- **Identity provider guides:** [Auth0, Clerk, Google, WorkOS](https://developer.nylas.com/docs/v3/auth/nylas-connect-react/use-external-idp/) +- **Developer forum:** [forums.nylas.com](https://forums.nylas.com/) +- **Changelog:** [CHANGELOG.md](CHANGELOG.md) + +## โœจ Upgrading + +See [`CHANGELOG.md`](CHANGELOG.md) for per-release notes. + +## ๐Ÿ’™ Contributing + +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. + +## ๐Ÿ”’ Security + +Found a vulnerability? Please **don't** open a public issue. Report it through our [Vulnerability Disclosure Policy](https://www.nylas.com/security/vulnerability-disclosure-policy/). + +## ๐Ÿ”— Other Nylas SDKs -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). +- [@nylas/connect](https://github.com/nylas/javascript/tree/main/packages/nylas-connect) ยท `npm install @nylas/connect` +- [nylas-nodejs](https://github.com/nylas/nylas-nodejs) ยท `npm install nylas` +- [nylas-python](https://github.com/nylas/nylas-python) ยท `pip install nylas` +- [nylas-ruby](https://github.com/nylas/nylas-ruby) ยท `gem install nylas` +- [nylas-java](https://github.com/nylas/nylas-java) ยท Maven / Gradle (Kotlin too) -### Further reading: +## ๐Ÿ“ License -- [Scheduler documentation](https://developer.nylas.com/docs/v3/scheduler/) -- [Scheduler API reference](https://developer.nylas.com/docs/api/v3/scheduler/) -- [Developer Forums](https://forums.nylas.com/) +MIT โ€” see [LICENSE.md](LICENSE.md). From 01898ba93f98e0d9aacc5a823e8eb484b9771171 Mon Sep 17 00:00:00 2001 From: Nick Barraclough Date: Tue, 1 Sep 2026 13:08:22 -0500 Subject: [PATCH 3/3] docs(@nylas/react): document the utils subpath The subpath table omitted @nylas/react/utils, which is a real entry in the package.json exports map. Noted in review on #97. Co-Authored-By: Claude Opus 5 (1M context) --- packages/react/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/react/README.md b/packages/react/README.md index cd1f70c..d853e55 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -58,6 +58,7 @@ The package ships its own TypeScript types, and exposes three subpaths so you on | --- | --- | | `@nylas/react` | Everything below except the Connect symbols | | `@nylas/react/elements` | Scheduler and booking components | +| `@nylas/react/utils` | `NylasIdentityRequestWrapper`, and the `LANGUAGE_CODE` type | | `@nylas/react/connect` | `useNylasConnect`, `NylasConnectButton`, and re-exports of `@nylas/connect` | > **Note:** `useNylasConnect` and `NylasConnectButton` are available **only** from `@nylas/react/connect`, not from the package root.