Installation

Install the package along with its peer dependencies.

npm install @chemmangat/msal-next @azure/msal-browser @azure/msal-react

Quick Start

1. Configure Environment

.env.local

NEXT_PUBLIC_CLIENT_ID=your-client-id
NEXT_PUBLIC_TENANT_ID=your-tenant-id

2. Wrap Your App

app/layout.tsx

import { MSALProvider } from '@chemmangat/msal-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MSALProvider
          clientId={process.env.NEXT_PUBLIC_CLIENT_ID!}
        >
          {children}
        </MSALProvider>
      </body>
    </html>
  );
}

3. Use the Hook

app/page.tsx

'use client';

import { MicrosoftSignInButton, useMsalAuth } from '@chemmangat/msal-next';

export default function Home() {
  const { isAuthenticated, account } = useMsalAuth();

  if (!isAuthenticated) {
    return <MicrosoftSignInButton />;
  }

  return <div>Hello, {account?.name}!</div>;
}

MSALProvider

The main provider component that initializes MSAL and wraps your application.

Props

clientIdstringrequired

Azure AD Application (client) ID

tenantIdstring

Azure AD Directory (tenant) ID (optional for multi-tenant)

autoRefreshTokenbooleanNew in v4.1

Enable automatic silent token refresh

Default: false

refreshBeforeExpirynumber

Seconds before expiry to refresh token

Default: 300

useMsalAuth Hook

The main hook for authentication operations in your components.

Return Values

isAuthenticatedboolean

Whether user is authenticated

accountAccountInfo | null

Current authenticated account

loginRedirect() => Promise<void>

logoutRedirect() => Promise<void>

Logout using redirect

Protected Routes (v4.0)

Protect any route with one line of code.

app/dashboard/page.tsx

export const auth = { required: true };

export default function Dashboard() {
  return <div>Protected content</div>;
}

Automatic Token Refresh (v4.1)

Prevent unexpected logouts with automatic silent token refresh.

app/layout.tsx

<MSALProvider
  clientId="..."
  autoRefreshToken={true}
  refreshBeforeExpiry={300}
>
  {children}
</MSALProvider>

MSAL v5 Compatibility (v5.2.0)

As of v5.2.0, msal-next supports @azure/msal-browser v3, v4, and v5, and @azure/msal-react v2 through v5. No changes are required in your application code — all API differences are handled transparently at runtime.

✓

You can upgrade @azure/msal-browser and @azure/msal-react to their latest versions without touching any msal-next configuration.

Supported peer dependency ranges

"@azure/msal-browser": "^3.11.0 || ^4.0.0 || ^5.0.0",
"@azure/msal-react":   "^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0"

What changed in MSAL Browser v5

The following breaking changes in msal-browser v5 are all handled internally by msal-next:

handleRedirectPromise() signature

v5 accepts a HandleRedirectPromiseOptions object instead of an optional hash string. navigateToLoginRequestUrl is now passed here rather than in the MSAL config.

storeAuthStateInCookie removed

Removed from CacheOptions in v5. msal-next detects the version at runtime and omits this option automatically when running on v5.

navigateToLoginRequestUrl removed from config

Removed from BrowserAuthOptions in v5. msal-next passes it to handleRedirectPromise() on v5 and to the config object on v3/v4.

LOGIN_SUCCESS payload type changed

In v5 the LOGIN_SUCCESS event payload is AccountInfo directly. In v3/v4 it was AuthenticationResult with an .account property. msal-next handles both shapes.

LOGIN_FAILURE event removed

Removed in v5 — login failures now surface as ACQUIRE_TOKEN_FAILURE. msal-next listens to both so errors are never silently dropped.

Upgrading

To use the latest MSAL packages, just update your dependencies:

npm install @azure/msal-browser@latest @azure/msal-react@latest

No other changes required. msal-next v5.2.0 handles the rest.