Netlify Auth Providers

1.0.0-alpha5 verified Sat Apr 25 auth: no javascript deprecated

Netlify Auth Providers is an alpha-stage library (v1.0.0-alpha5) for authenticating with Netlify's external OAuth providers. It provides a simple client that handles the authentication flow, token storage, and refresh. As an alpha release, the API is unstable and may change without notice. Key differentiators include direct integration with Netlify's Identity service and minimal configuration required.

Common errors

error TypeError: netlify_auth_providers_1.default is not a constructor ↓

cause Using CommonJS require on an ESM-only package.

fix

Use ES module import syntax (import ... from).

error Error: Could not find provider 'github'. Available providers: [] ↓

cause Provider list not initialized or incorrect provider name.

fix

Specify provider in options object (case-sensitive).

error OAuth callback failed: invalid redirect_uri ↓

cause Redirect URI does not match Netlify app settings.

fix

Ensure the redirectUri matches exactly what is configured in Netlify dashboard.

Warnings

breaking Alpha release: no stable API; breaking changes occur without warning. ↓

fix Pin to exact version and test each upgrade.

deprecated Package is deprecated in favor of netlify-identity-widget or direct Identity API. ↓

fix Migrate to netlify-identity-widget for UI integration or use Netlify Identity JS client.

gotcha OAuth redirect must be handled on the same origin; CORS errors occur if mismatched. ↓

fix Ensure redirectUri matches the exact page where handleCallback is called.

gotcha Token storage defaults to localStorage; may not be available in SSR environments. ↓

fix Implement custom TokenStore that uses cookies or other storage.

Install

npm install netlify-auth-providers

yarn add netlify-auth-providers

pnpm add netlify-auth-providers

Imports

default

wrong

const NetlifyAuthProviders = require('netlify-auth-providers')

correct

import NetlifyAuthProviders from 'netlify-auth-providers'

ESM-only package; CommonJS require is not supported.

Authenticator

import { Authenticator } from 'netlify-auth-providers'

Exported class for managing OAuth flows.

TokenStore
```
import { TokenStore } from 'netlify-auth-providers'
```
Interface for custom token storage; not exported in earlier alphas.

Quickstart

Demonstrates initializing the client, starting OAuth, handling callback, and retrieving token.

import NetlifyAuthProviders from 'netlify-auth-providers';

const client = new NetlifyAuthProviders({
  provider: 'github',
  clientId: process.env.GITHUB_CLIENT_ID ?? '',
  redirectUri: 'http://localhost:8888/callback'
});

// Start OAuth flow
client.authenticate();

// After redirect, handle callback
client.handleCallback();

// Get access token
const token = client.getToken();
console.log({ token });