Modern, lightweight Nylas connection library with PKCE support
npm install @nylas/connect


> 🚀 Modern, secure, developer-friendly OAuth connection for Nylas APIs
- 🔒 Secure by default - PKCE flow, automatic token management, no secrets in browser
- ⚡ Zero dependencies - Lightweight, fast, and reliable
- 🎯 TypeScript-first - Full type safety and IntelliSense support
- 🌐 Universal - Works in modern browsers and Node.js 18+
- 📱 Flexible flows - Popup (recommended) or redirect authentication
- 💾 Smart persistence - Automatic session and token storage
``bash`
npm install @nylas/connect
Prerequisites: Node.js 18+ and a modern browser
`typescript
import { NylasConnect } from '@nylas/connect';
const nylasConnect = new NylasConnect({
clientId: 'your-nylas-client-id',
redirectUri: 'http://localhost:3000/auth/callback'
});
// Connect with popup (recommended)
const result = await nylasConnect.connect({ method: 'popup' });
console.log('Connected as:', result.email);
`
Environment variables (recommended):
`typescript`
// Use environment variables
const nylasConnect = new NylasConnect();
// Reads from NYLAS_CLIENT_ID and NYLAS_REDIRECT_URI
`typescript`
const result = await nylasConnect.connect({ method: 'popup' });
- User stays in your app
- Seamless experience
- Best for SPAs
`typescript`
const url = await nylasConnect.connect({ method: 'inline' });
window.location.href = url;
- Full page redirect
- Works when popups blocked
- Better for mobile
`typescript`
// At your redirect URI (e.g., /auth/callback)
await nylasConnect.callback();
`env`
NYLAS_CLIENT_ID=your-nylas-client-id
NYLAS_REDIRECT_URI=http://localhost:3000/auth/callback
Note: With modern bundlers, prefix environment variables:
- Vite: VITE_NYLAS_CLIENT_IDNEXT_PUBLIC_NYLAS_CLIENT_ID
- Next.js:
`typescript
// Check current session
const session = await nylasConnect.getSession();
if (session) {
console.log('User:', session.grantInfo?.email);
}
// Logout
await nylasConnect.logout();
`
`typescript`
try {
await nylasConnect.connect({ method: 'popup' });
} catch (error) {
console.error('Connection failed:', error.message);
}
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| clientId | string | - | Nylas Client ID |redirectUri
| | string | - | OAuth redirect URI |apiUrl
| | string | https://api.us.nylas.com | API base URL |persistTokens
| | boolean | true | Store tokens in localStorage |debug
| | boolean | true on localhost | Enable debug logging |codeExchange
| | (param: CodeExchangeParams) => Promise | - | Custom code exchange method |
For enhanced security, you can handle the OAuth code exchange on your backend instead of in the browser. This approach keeps your API keys secure and gives you full control over the token exchange process.
``typescript
const nylasConnect = new NylasConnect({
clientId: 'your-nylas-client-id',
redirectUri: 'http://localhost:3000/auth/callback',
codeExchange: async (params) => {
// Send the authorization code to your backend
const response = await fetch('/api/auth/exchange', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
code: params.code,
state: params.state,
clientId: params.clientId,
redirectUri: params.redirectUri,
scopes: params.scopes,
provider: params.provider,
}),
});
if (!response.ok) {
throw new Error(Token exchange failed: ${response.statusText});
}
const tokenData = await response.json();
// Return the expected ConnectResult format
return {
accessToken: tokenData.access_token,
idToken: tokenData.id_token,
grantId: tokenData.grant_id,
expiresAt: Date.now() + tokenData.expires_in * 1000,
scope: tokenData.scope,
grantInfo: tokenData.grant_info,
};
}
});
// Use normally - the custom exchange will be called automatically
const result = await nylasConnect.connect({ method: 'popup' });
`
`typescriptBearer ${process.env.NYLAS_API_KEY}
// Example backend endpoint (/api/auth/exchange)
export async function POST(request: Request) {
const { code, clientId, redirectUri } = await request.json();
// Exchange code for tokens using your API key
const response = await fetch('https://api.us.nylas.com/connect/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': ,
},
body: new URLSearchParams({
client_id: clientId,
redirect_uri: redirectUri,
code,
grant_type: 'authorization_code',
}),
});
const tokenData = await response.json();
return Response.json(tokenData);
}
`
Start OAuth flow. Returns ConnectResult for popup or URL string for redirect.
`typescript
// Popup
await nylasConnect.connect({ method: 'popup' });
// Redirect
const url = await nylasConnect.connect({ method: 'inline' });
`
Handle OAuth callback. Auto-detects current URL if none provided.
Get current session. Returns null if no active session.
Clear stored tokens and logout.
For server-side token exchange:
`typescript
// Client: build auth URL without PKCE
const { url, state } = await nylasConnect.getAuthUrl();
window.location.href = url;
// Server: exchange code using Nylas Node SDK
const { grantId } = await nylas.auth.exchangeCodeForToken({
clientId: process.env.NYLAS_CLIENT_ID,
clientSecret: process.env.NYLAS_CLIENT_SECRET,
code: req.query.code,
redirectUri: process.env.NYLAS_REDIRECT_URI
});
`
`typescript`
await nylasConnect.connect({
method: 'popup',
scopes: ['https://www.googleapis.com/auth/gmail.readonly']
});
`typescript
const unsubscribe = nylasConnect.onConnectStateChange((event, session) => {
if (event === 'CONNECT_SUCCESS') {
console.log('Connected:', session?.grantInfo?.email);
}
});
// Clean up
unsubscribe();
`
Popup: Better UX, works in SPAs, requires popup permission
Redirect: Works everywhere, better for mobile, full page navigation
Usually no. Nylas handles default scopes automatically. Override only for specific provider permissions.
Match your Nylas account region:
- US: https://api.us.nylas.comhttps://api.eu.nylas.com
- EU:
Automatic. @nylas/connect handles token refresh in the background.
This example demonstrates how to use the new identityProviderToken callback feature to integrate external identity providers (via JWKS) with Nylas Connect.
`typescript
import { NylasConnect } from '@nylas/connect';
// Example: Using a function that returns a JWT token
const connect = new NylasConnect({
clientId: 'your-client-id',
redirectUri: 'http://localhost:3000/auth/callback',
// New feature: Identity provider token callback
identityProviderToken: async () => {
// Your logic to get the JWT token from your external identity provider
// This could be from your own auth system, a third-party service, etc.
const token = await getJWTFromYourIdentityProvider();
return token; // Return the JWT string, or null if not available
}
});
// The rest works the same as before
const result = await connect.connect({ method: 'popup' });
`
1. When you call connect.connect(), the authentication flow proceeds normallyidentityProviderToken
2. During the token exchange step (when exchanging the authorization code for access tokens), the callback is calledidp_claims
3. If the callback returns a JWT token, it's sent to Nylas as the parameternull
4. If the callback returns or throws an error:null
- Returning : The auth flow continues without IDP claimsNETWORK_ERROR
- Throwing an error: The entire token exchange fails with a event
If the identityProviderToken callback throws an error, the entire authentication flow will fail with a NETWORK_ERROR event. You can listen for this event to handle IDP-related errors:
`typescript``
connect.onConnectStateChange((event, session, data) => {
if (event === 'NETWORK_ERROR' && data?.operation === 'identity_provider_token_callback') {
// Handle IDP token callback error
console.error('IDP token error:', data.error);
}
});
MIT © Nylas