Migrar do MSAL React v3 para v5

Note

Não há nenhuma versão do MSAL React v4. A versão do pacote foi incrementada da v3 diretamente para a v5 para alinhar o controle de versão de msal-react ao das outras bibliotecas MSAL.js. Não existe nenhum conjunto de recursos v4 separado.

Consulte o guia de migração do MSAL Browser v4-v5 para obter suporte ao navegador e outras alterações importantes.

Caminhos de migração

  • v3 -> v5: Siga este guia e, em seguida, aplique o guia de migração do MSAL Browser v4-v5, especialmente a configuração da ponte de redirecionamento.
  • v1/v2 -> v5: As atualizações v1 -> v2 e v2 -> v3 foram apenas atualizações de versão de dependências de mesmo nível para a maioria dos aplicativos. Migre primeiro para a v3 e, em seguida, siga as orientações de v3 -> v5 neste documento, além da configuração da ponte de redirecionamento.

Configuração da ponte de redirecionamento (obrigatório)

O MSAL Browser v5 requer uma página/ponte de redirecionamento dedicada para fluxos de autenticação.

Consulte a seção COOP no guia de migração do NAVEGADOR MSAL v4-v5.

Suporte descartado para versões antigas do React

O MSAL React v5 dá suporte ao React 19.2.1 ou superior. Ele não dá mais suporte ao React 16, 17 ou 18.

Observação de compatibilidade do React 18

Warning

O React 18 atingiu o fim da vida útil, e é por isso que o MSAL React v5 abandonou o suporte para ele.

Se o aplicativo ainda estiver no React 18, a instalação @azure/msal-react@^5 poderá falhar devido a restrições de dependência par.

  • Solução alternativa de instalação temporária: npm install --legacy-peer-deps
  • Isso pode permitir a instalação e os fluxos básicos podem continuar funcionando em alguns aplicativos, mas o React 18 não tem suporte ou é validado para v5
  • Você pode observar comportamentos não testados relacionados à temporização da renderização/do ciclo de vida, a interações com o StrictMode ou a futuras atualizações de patch.

Para cargas de trabalho de produção, atualize o React para 19.2.1 ou superior antes de migrar para @azure/msal-react@^5.

Migrando do Create React App (react-scripts)

Criar aplicativo React foi preterido e react-scripts não dá suporte ao React 19. Se o aplicativo usar react-scripts, você deverá migrar para uma ferramenta de build diferente antes de atualizar para @azure/msal-react@^5.

Recomendado: migrar para Vite

  1. Remova react-scripts e instale o Vite + o plugin do React:

    npm uninstall react-scripts
npm install --save-dev vite @vitejs/plugin-react

  2. Adicione "type": "module" a package.json.

  3. Mova public/index.html para a raiz do projeto como index.html, substitua as referências a %PUBLIC_URL%/ por / e adicione a tag de script do ponto de entrada:

    <!-- Before (CRA): no script tag needed, CRA injects it -->
<!-- After (Vite): add before </body> -->
<script type="module" src="/src/index.jsx"></script>

  4. Crie um(a) vite.config.js na raiz do projeto:

    import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { resolve } from "path";

export default defineConfig({
    plugins: [react()],
    server: {
        port: 3000,
    },
    build: {
        rollupOptions: {
            input: {
                main: resolve(__dirname, "index.html"),
                redirect: resolve(__dirname, "public/redirect.html"),
            },
        },
    },
});

  5. Atualizar package.json scripts:

    "scripts": {
    "start": "vite",
    "build": "vite build",
    "preview": "vite preview"
}

  6. Substitua as referências process.env.REACT_APP_* por import.meta.env.VITE_* e renomeie as variáveis de ambiente de acordo (por exemplo, REACT_APP_CLIENT_ID → VITE_CLIENT_ID).

  7. Remova as variáveis de ambiente específicas do CRA (SKIP_PREFLIGHT_CHECK, DISABLE_ESLINT_PLUGIN) dos .env arquivos.

  8. Atualize o React e instale a MSAL:

    npm install react@^19.2.1 react-dom@^19.2.1
npm install @azure/msal-browser@^5 @azure/msal-react@^5

  9. Configure a ponte de redirecionamento para seu aplicativo Vite.

Amostras: Consulte o react-router-sample, typescript-sample e b2c-sample para obter exemplos completos baseados em Vite.

Corrigir o bug de logout

MSAL React v5 corrigiu um bug que afetava o hook useMsalAuthentication e MsalAuthenticationTemplate. Agora, ao encerrar a sessão, todo o estado associado ao usuário é limpo.

InteractionStatus Alterações

Para InteractionStatus: Login, SsoSilente AcquireToken agora estão consolidados em AcquireToken.

Exemplo de migração

Se o aplicativo verificava anteriormente vários status em andamento, simplifique para o status consolidado AcquireToken.

import { InteractionStatus } from "@azure/msal-browser";

// Before (v3-style checks)
const tokenInteractionInProgress =
	inProgress === InteractionStatus.Login ||
	inProgress === InteractionStatus.SsoSilent ||
	inProgress === InteractionStatus.AcquireToken;

// After (v5)
const tokenInteractionInProgress =
	inProgress === InteractionStatus.AcquireToken;

if (!tokenInteractionInProgress) {
	// safe to initiate a new auth/token request
}
  • Last updated on