Next.js Firebase Authentication for Edge and Node.js runtimes. Use Firebase Authentication with latest Next.js features.

Example

Check out a working demo here: next-firebase-auth-edge-starter.vercel.app

You can find the source code for this demo at examples/next-typescript-starter

Featured in

<picture> <source media="(prefers-color-scheme: dark)" srcset="images/ensite-logo-horizontal-white.svg"> <source media="(prefers-color-scheme: light)" srcset="images/ensite-logo-horizontal.svg"> </picture>

Guide

New to Firebase or Next.js? No worries! Follow this easy, step-by-step guide to set up Firebase Authentication in Next.js app using the next-firebase-auth-edge library:

https://hackernoon.com/using-firebase-authentication-with-the-latest-nextjs-features

Docs

The official documentation is available here: https://next-firebase-auth-edge-docs.vercel.app

Why?

The official firebase-admin library depends heavily on Node.js’s internal crypto library, which isn’t available in Next.js Edge Runtime.

This library solves that problem by handling the creation and verification of Custom ID Tokens using the Web Crypto API, which works in Edge runtimes.

Features

next-firebase-auth-edge supports all the latest Next.js features, like the App Router and Server Components.

To make adopting the newest Next.js features easier, this library works seamlessly with both getServerSideProps and legacy API Routes.

Key Features:

• Supports Next.js's latest features
• Zero bundle size
• Minimal setup: Unlike other libraries, you won’t need to create your own API routes or modify your next.config.js. Everything’s handled by middleware.
• Secure: Uses jose for JWT validation, and signs user cookies with rotating keys to prevent cryptanalysis attacks.

What's New

Key updates in latest release include:

• Added removeServerCookies method to handle logout from inside Server Action
• Added experimental_createAnonymousUserIfUserNotFound option to create anonymous user if no user was found
• Full Firebase Emulator Support. The library now fully supports the Firebase Emulator, enabling you to run your development app without needing to create a Firebase Project. Follow starter example README for details
• Custom token is now optional. To enable custom token support use enableCustomToken option
• Support ESM, Browser and Node.js imports for better tree-shaking features
• Support for Node.js 23 and NPM 11
• Support for Next.js 15
• Support for React 19 RC
• New experimental_enableTokenRefreshOnExpiredKidHeader option in authMiddleware and getTokens, which refreshes user tokens when Google’s public certificates expire (instead of throwing an error)

Installation

To install, run one of the following:

With npm

npm install next-firebase-auth-edge

With yarn

yarn add next-firebase-auth-edge

With pnpm

pnpm add next-firebase-auth-edge

→ Read the docs

1.9.1 (2025-02-18)

Bug Fixes

• dynamic-custom-claims: allow to update claims after token refresh (475e767)

1.9.0 (2025-02-18)

Bug Fixes

• #297: propagate custom claims when exchanging id token for custom, id and refresh tokens (55254b8), closes #297
• #303: support npm 11 (88328e5), closes #303
• #306: support Node.js 23 (f27d210), closes #306
• return cached token or server token (c1a04a9)
• return cached valid token (a73f9ec)

Features

• #300: added removeServerCookies method to logout from Server Actions (cab2d23), closes #300
• full firebase emulator support (9dcf5e9)

1.9.0-canary.6 (2025-01-28)

Bug Fixes

• #306: support Node.js 23 (f27d210), closes #306

1.9.0-canary.5 (2025-01-23)

Bug Fixes

• #303: support npm 11 (88328e5), closes #303

1.9.0-canary.4 (2025-01-22)

Features

• #300: added removeServerCookies method to logout from Server Actions (cab2d23), closes #300

1.9.0-canary.3 (2025-01-21)

Bug Fixes

• #297: propagate custom claims when exchanging id token for custom, id and refresh tokens (55254b8), closes #297

1.9.0-canary.2 (2024-12-16)

Bug Fixes

• return cached token or server token (c1a04a9)
• return cached valid token (a73f9ec)

1.9.0-canary.1 (2024-11-15)

Features

• full firebase emulator support (9dcf5e9)

1.8.2 (2024-11-07)

Bug Fixes

• docs: added await before calling cookies and headers due to change in Next.js 15 (d14c9df)
• add logs to invalid token comparator func (11eaede)
• added additional logs around cookie parser (1550c80)
• added additional logs to debug a failed verification in auth middleware (30ddc5e)
• await on parse cookie result to work around #271 (f6b5106)
• debug Vercel logging by removing inheritance from Error (46ca356)
• export error module explicitly (575281c)
• remove console.log and improve debug logs around token fetching (31dfbd2)
• remove debug logs from cookie parser (2ce3190)
• remove unnecessary async in get tokens functions (c0f530c)
• work around #271 in getCookiesTokens (5fef799)
• #271: use runtime flag to identify invalid token error (d7220b0), closes #271

1.8.2-canary.11 (2024-11-07)

Bug Fixes

• docs: added await before calling cookies and headers due to change in Next.js 15 (d14c9df)

1.8.2-canary.10 (2024-11-06)

Bug Fixes

• remove unnecessary async in get tokens functions (c0f530c)
• work around #271 in getCookiesTokens (5fef799)

1.8.2-canary.9 (2024-11-06)

Bug Fixes

• await on parse cookie result to work around #271 (f6b5106)

1.8.2-canary.8 (2024-11-06)

Bug Fixes

• remove debug logs from cookie parser (2ce3190)

1.8.2-canary.7 (2024-11-06)

Bug Fixes

• added additional logs around cookie parser (1550c80)

1.8.2-canary.6 (2024-11-06)

Bug Fixes

• debug Vercel logging by removing inheritance from Error (46ca356)

1.8.2-canary.5 (2024-11-06)

Bug Fixes

• remove console.log and improve debug logs around token fetching (31dfbd2)

1.8.2-canary.4 (2024-11-06)

Bug Fixes

• add logs to invalid token comparator func (11eaede)

1.8.2-canary.3 (2024-11-06)

Bug Fixes

• #271: use runtime flag to identify invalid token error (d7220b0), closes #271

1.8.2-canary.2 (2024-11-06)

Bug Fixes

• export error module explicitly (575281c)

1.8.2-canary.1 (2024-11-06)

Bug Fixes

• added additional logs to debug a failed verification in auth middleware (30ddc5e)

1.8.1 (2024-11-05)

Bug Fixes

• update cookie library to avoid vulnerability in cookie < 0.7.0 (0940e28)

1.8.0 (2024-10-28)

Bug Fixes

• added circular import validation (deaa2e3)
• automated release build cache (b6abf5a)
• create request cookies provider from cloned headers (d17c376)
• include missing directories in package.json exports (668ae8b)
• remove declarations from esm build (025e4c8)

Features

• make custom token optional (4a18cb7)
• refactor cookies to separate multiple from single type (9aba786)
• support esm, commonjs and browser build targets (93a17bd)
• validate tenantId when verifying id token (798d0f1)

1.8.0-canary.9 (2024-10-09)

Features

• make custom token optional (4a18cb7)

1.8.0-canary.8 (2024-09-30)

Bug Fixes

• create request cookies provider from cloned headers (d17c376)

1.8.0-canary.7 (2024-09-30)

Bug Fixes

• added circular import validation (deaa2e3)

1.8.0-canary.6 (2024-09-29)

Features

• refactor cookies to separate multiple from single type (9aba786)

1.8.0-canary.5 (2024-09-22)

Bug Fixes

• include missing directories in package.json exports (668ae8b)

1.8.0-canary.4 (2024-09-22)

Bug Fixes

• automated release build cache (b6abf5a)

1.8.0-canary.3 (2024-09-22)

Bug Fixes

• remove declarations from esm build (025e4c8)

1.8.0-canary.2 (2024-09-22)

Features

• support esm, commonjs and browser build targets (93a17bd)

1.8.0-canary.1 (2024-09-21)

Features

• validate tenantId when verifying id token (798d0f1)

1.7.1 (2024-09-13)

Bug Fixes

• handle switch from multiple to single cookie (9b18bd5)

1.7.0 (2024-09-09)

Bug Fixes

• add debug logs for experimental feature (41ef1df)
• #242: use TextEncoder when mapping token to UInt8Array (23b04dc), closes #242
• #246: re-throw invalid PKCS8 error as AuthError with user-friendly message (a7d7a22), closes #246
• #249: merge error stack trace in token verifier to improve visibility on fetch errors (6bce756), closes #249
• add missing name property to decoded id token type (39b086d)
• pass cookie serialization options to cookie setter (b28ce7a)
• recreate canary tags after force push (c9b7c18)
• semantic-release rate exceeded error (676b602)
• semantic-version git history issue (d514f57)
• update next.js peer dependency to rc (f2953fd)

Features

• middleware: introduced redirectToPath method and RegExp support in redirectToLogin method (21024bb)
• added path option to redirectToHome helper function (54f07f4)
• allow setAuthCookies to accept custom auth headers or fall back (b1d169b)
• experimental option to refresh token on expired kid header (2869531)
• introduced refreshCookiesWithIdToken function to enable login using Server Actions (#212) (6cd0b13)
• next.js 15 rc support (a994dd0)
• pass custom auth header from authMiddleware (71286af)
• getTokens: introduced optional cookieSerializeOptions option (e041542)
• replaced no matching kid auth error with invalid token error (9d2d0fc)
• support Node.js 22 (6c7f435)

1.7.0-canary.17 (2024-09-07)

Features

• middleware: introduced redirectToPath method and RegExp support in redirectToLogin method (21024bb)

1.7.0-canary.16 (2024-09-06)

Features

• allow setAuthCookies to accept custom auth headers or fall back (b1d169b)
• pass custom auth header from authMiddleware (71286af)

1.7.0-canary.15 (2024-09-06)

Bug Fixes

• add debug logs for experimental feature (41ef1df)

1.7.0-canary.14 (2024-09-06)

Features

• experimental option to refresh token on expired kid header (2869531)

1.7.0-canary.13 (2024-09-03)

Bug Fixes

• #249: merge error stack trace in token verifier to improve visibility on fetch errors (6bce756), closes #249

1.7.0-canary.12 (2024-09-03)

Bug Fixes

• #242: use TextEncoder when mapping token to UInt8Array (23b04dc), closes #242

1.7.0-canary.11 (2024-08-30)

Bug Fixes

• #246: re-throw invalid PKCS8 error as AuthError with user-friendly message (a7d7a22), closes #246

1.7.0-canary.10 (2024-08-22)

Features

• getTokens: introduced optional cookieSerializeOptions option (e041542)

1.7.0-canary.9 (2024-08-21)

Bug Fixes

• pass cookie serialization options to cookie setter (b28ce7a)

1.7.0-canary.8 (2024-08-21)

Features

• replaced no matching kid auth error with invalid token error (9d2d0fc)

1.7.0-canary.7 (2024-08-21)

Features

• support Node.js 22 (6c7f435)

1.7.0-canary.6 (2024-08-10)

Bug Fixes

• semantic-release rate exceeded error (676b602)

1.7.0-canary.5 (2024-08-10)

Bug Fixes

• update next.js peer dependency to rc (f2953fd)

1.7.0-canary.4 (2024-08-10)

Bug Fixes

• add missing name property to decoded id token type (39b086d)

Features

• next.js 15 rc support (a994dd0)

1.7.0-canary.3 (2024-08-08)

Bug Fixes

• recreate canary tags after force push (c9b7c18)
• semantic-version git history issue (d514f57)

1.7.0-canary.2 (2024-07-25)

Features

• added path option to redirectToHome helper function (54f07f4)

1.7.0-canary.1 (2024-07-16)

Features

• introduced refreshCookiesWithIdToken function to enable login using Server Actions (#212) (fd6b193)

1.6.2 (2024-07-16)

Bug Fixes

• fix JWSInvalid: Invalid Compact JWS error when migrating between token formats (#214) (5b6b0c3)

1.6.1 (2024-07-15)

Bug Fixes

• rename appendEmptyResponseHeaders to removeCookies (498d044)

1.6.0 (2024-07-15)

Bug Fixes

• enable refresh token route (d081c22)
• fix "process is not defined" error in cloudflare worker #192 (6a94587)
• return null from getValidIdToken if provided server token is empty (613f230)
• store latest valid id token on client (5764a33)
• suppress unknown headers property error (1459ba9)

Features

• added getValidCustomToken method and documented client-side SDK usage (2261ef9)
• exposed customToken in handleValidToken, getTokens and getFirebaseAuth methods (f95c34c)
• introduced enableMultipleCookies auth middleware option to increase token capacity (23ee02f)
• introduced refreshTokenPath middleware option and getValidIdToken client method (56e07c5)
• introduced removeCookie method (f108984)
• support for async response factory in refreshCredentials method (25bf5c4)

1.6.0-canary.9 (2024-07-14)

Features

• introduced enableMultipleCookies auth middleware option to increase token capacity (23ee02f)

1.6.0-canary.8 (2024-07-14)

Features

• added getValidCustomToken method and documented client-side SDK usage (2261ef9)

1.6.0-canary.7 (2024-07-07)

Bug Fixes

• suppress unknown headers property error (1459ba9)

Features

• exposed customToken in handleValidToken, getTokens and getFirebaseAuth methods (f95c34c)

1.6.0-canary.6 (2024-06-17)

Bug Fixes

• return null from getValidIdToken if provided server token is empty (613f230)

1.6.0-canary.5 (2024-06-15)

Bug Fixes

• store latest valid id token on client (5764a33)

1.6.0-canary.4 (2024-06-15)

Bug Fixes

• enable refresh token route (d081c22)

1.6.0-canary.3 (2024-06-15)

Features

• introduced refreshTokenPath middleware option and getValidIdToken client method (56e07c5)

1.6.0-canary.2 (2024-06-05)

Features

• introduced removeCookie method (f108984)

1.6.0-canary.1 (2024-06-05)

Features

• support for async response factory in refreshCredentials method (25bf5c4)

1.5.4-canary.1 (2024-06-01)

Bug Fixes

• fix "process is not defined" error in cloudflare worker #192 (6a94587)

1.5.3 (2024-05-31)

Bug Fixes

• referer is now based on caller host (2f75386)

1.5.2 (2024-05-30)

Bug Fixes

• expose tokens in refreshCredentials response factory callback (644b8a2)

1.5.1 (2024-05-30)

Bug Fixes

• reintroduce refreshAuthCookies as refreshNextResponseCookiesWithToken (620f986)

1.5.0 (2024-05-30)

Bug Fixes

• remove fetch cache: no-store due to https://github.com/awinogrodzki/next-firebase-auth-edge/issues/173 (6fb8143)

Features

• added refreshCredentials method that allows to pass modified request headers to NextResponse constructor (2bf2877)
• extract referer from Next.js request headers (bc666fa)
• introduced Firebase API Key domain restriction support. Introduced changes to advanced methods and removed APIs deprecated in 1.0 (67dbb9a)

Performance Improvements

• refreshCredentials: slightly improve performance by generating signed tokens only once (da2fc3e)

1.5.0-canary.5 (2024-05-30)

Features

• extract referer from Next.js request headers (bc666fa)

1.5.0-canary.4 (2024-05-27)

Performance Improvements

• refreshCredentials: slightly improve performance by generating signed tokens only once (da2fc3e)

1.5.0-canary.3 (2024-05-27)

Features

• added refreshCredentials method that allows to pass modified request headers to NextResponse constructor (2bf2877)

1.5.0-canary.2 (2024-05-26)

Bug Fixes

• remove fetch cache: no-store due to https://github.com/awinogrodzki/next-firebase-auth-edge/issues/173 (6fb8143)

1.5.0-canary.1 (2024-05-26)

Features

• introduced Firebase API Key domain restriction support. Introduced changes to advanced methods and removed APIs deprecated in 1.0 (67dbb9a)

1.4.5 (2024-05-26)

Bug Fixes

• /api/login endpoint now fails with 400: Missing Token error when called without credentials (2997fc5)
• exclude lib folder from npmignore file (f7ef2d5)
• fix build cache path in github workflows (df4c98d)
• remove .env.dist from npm package (5c136f9)
• remove tests and lint steps from semantic release pipeline (160662d)
• semantic release npm publish initialization (3ed6ef5)
• semantic release package configuration (ec93cc6)
• set correct pkgRoot in semantic releases configuration (9c36948)

1.4.5-canary.7 (2024-05-26)

Bug Fixes

• fix build cache path in github workflows (df4c98d)

1.4.5-canary.6 (2024-05-26)

Bug Fixes

• exclude lib folder from npmignore file (f7ef2d5)

1.4.5-canary.5 (2024-05-26)

Bug Fixes

• remove tests and lint steps from semantic release pipeline (160662d)

1.4.5-canary.4 (2024-05-26)

Bug Fixes

• set correct pkgRoot in semantic releases configuration (9c36948)

1.4.5-canary.2 (2024-05-26)

Bug Fixes

• remove .env.dist from npm package (5c136f9)

1.4.5-canary.1 (2024-05-26)

Bug Fixes

• /api/login endpoint now fails with 400: Missing Token error when called without credentials (2997fc5)
• semantic release npm publish initialization (3ed6ef5)

1.4.4 (2024-05-26)

Bug Fixes

• disable default tag behavior in yarn publish (1661468)
• lint (c703cfb)
• semantic release publish step authorization (232f624)
• semantic release publish step git author (c917de4)

1.4.4-canary.1 (2024-05-26)

Bug Fixes

• disable default tag behavior in yarn publish (1661468)
• lint (c703cfb)
• semantic release publish step authorization (232f624)
• semantic release publish step git author (c917de4)

1.4.3

Patch Changes

• Remove digest from debug logs

1.4.2

Patch Changes

• Fetch Google public keys with cache: "no-store" to fix #159

1.4.1

Patch Changes

• Improve cookieSignatureKeys input validation

1.4.0

Minor Changes

• handleInvalidToken is now called with InvalidTokenReason as the first argument. It gives developers more inslight and control over authentication flow

1.3.0

Minor Changes

• The library now stores tokens and signature in a single cookie, allowing to run in Firebase Hosting environment
• Use the library without service account in authenticated Google Cloud Run environment
• Added debug mode option

1.2.0

Minor Changes

• Introduced refreshServerCookies method to refresh credentials from inside Server Actions

1.1.0

Minor Changes

• Deprecated refreshAuthCookies methods in favor of refreshNextResponseCookies and refreshApiResponseCookies

1.0.1

Patch Changes

• Update middleware token verification caching doc link

1.0.0

Major Changes

• Reworked APIs

0.11.2

Patch Changes

• Added getUserByEmail method

0.11.1

Patch Changes

• Added Node.js 20 support

0.11.0

Patch Changes

• Added App Check support

0.10.2

Patch Changes

• Stop displaying middleware verification cache warning on prefetched routes

0.10.1

Patch Changes

• Remove internal verification cookie on middleware request instead throwing an error
• Remove internal verification cookie on middleware request instead of throwing an error

0.10.0

Minor Changes

• Next.js 14 support

0.9.5

Patch Changes

• Skip response headers validation on redirect

0.9.4

Patch Changes

• Add list users function support

0.9.3

Patch Changes

• 964c04c: Check if the FIREBASE_AUTH_EMULATOR_HOST has already http:// added to it, otherwise you will get a cryptic fetch failed error.

0.9.2

Patch Changes

• Support tenantId in refreshAuthCookies

0.9.1

Patch Changes

• Return null if user was deleted from Firebase

0.9.0

Minor Changes

• Added middleware token verification caching

0.8.8

Patch Changes

• Add support for specifying tenantId in middleware

0.8.7

Patch Changes

• Convert signature key to UInt8Array directly instead using base64url.decode due to #92

0.8.6

Patch Changes

• Throw user friendly error on no matching kid in public keys response

0.8.5

Patch Changes

• Revalidate token against all public keys if kid is missing

0.8.4

Patch Changes

• Fix https://github.com/awinogrodzki/next-firebase-auth-edge/issues/90 by validating token against all returned public keys in case of not matching kid header

0.8.3

Patch Changes

• Fix no "kid" claim in idToken error when using emulator

0.8.2

Patch Changes

• Added createUser and updateUser methods

0.8.1

Patch Changes

• Remove 'cache: no-store' header from refreshExpiredIdToken

0.8.0

Minor Changes

• Refactor: remove custom JSON Web Token and Signature implementation in favor of jose

0.7.7

Patch Changes

• Fix Node.js 18.17 native WebCrypto ArrayBuffer compatibility issue

0.7.6

Patch Changes

• Import Next.js request cookie interfaces as type

0.7.5

Patch Changes

• Make caches optional due to Vercel Edge middleware error https://github.com/vercel/next.js/issues/50102

0.7.4

Patch Changes

• Set global cache before using ResponseCache

0.7.3

Patch Changes

• Use polyfill only if runtime is defined

0.7.2

Patch Changes

• Fix "body already used" error by cloning response upon rewriting

0.7.1

Patch Changes

• Added @edge-runtime/primitives to dependencies

0.7.0

Minor Changes

• Updated Next.js to 13.4 with stable app directory. Integrated edge-runtime and removed direct dependency to @peculiar/web-crypto. Integrated ServiceAccountCredential and PublicKeySignatureVerifier with Web APIs CacheStorage.

0.6.2

Patch Changes

• Update engines to support Node 19

0.6.1

Patch Changes

• Fix ReadonlyRequestCookies imports after update to Next.js 13.3.0

0.6.0

Minor Changes

• Added setCustomUserClaims, getUser and refreshAuthCookies Edge-runtime compatible methods

0.5.1

Patch Changes

• Handle refresh token error using handleError function
• Updated dependencies
  • next-firebase-auth-edge@0.5.1

0.5.0

Minor Changes

• Rename methods from getAuthenticatedResponse, getUnauthenticatedResponse and getErrorResponse to more readable handleValidToken, handleInvalidToken and handleError functions

0.4.4

Patch Changes

• Added refreshAuthCookies method to refresh cookie headers in api middleware

0.4.3

Patch Changes

• Introduced getUnauthenticatedResponse middleware option to handle redirects for unauthenticated users

0.4.2

Patch Changes

• getAuthenticatedResponse and getErrorResponse options are now async

0.4.1

Patch Changes

• Optional redirectOptions for use-cases where authentication happens in more than one contexts

0.4.0

Minor Changes

• Added authentication middleware to automatically handle redirection and authentication cookie refresh

0.3.1

Patch Changes

• Re-throw INVALID_CREDENTIALS FirebaseAuthError with error details on token refresh error

0.3.0

Minor Changes

• Updated peer next peer dependency to ^13.1.1 and removed allowMiddlewareResponseBody flag'

0.2.15

Patch Changes

• Handle "USER_NOT_FOUND" error during token refresh

0.2.14

Patch Changes

• Added Firebase Authentication Emulator support

0.2.13

Patch Changes

• Fix incorrect HMAC algorithm key buffer size

0.2.12

Patch Changes

• Update rotating credential HMAC key algorithm to SHA-512

0.2.11

Patch Changes

• Update rotating credential HMAC key algorithm to SHA-256

0.2.10

Patch Changes

• Support Next.js 18 LTS

0.2.9

Patch Changes

• Update Next.js peerDependency version to ^13.0.5 to allow future minor/patch versions

0.2.8

Patch Changes

• Integrated with changesets and eslint to improve transparency and legibility