Migrate AppProvider from Polaris React

AppProvider has no Polaris web component replacement. Keep it while any mounted subtree still renders a component from @shopify/polaris. After the final Polaris React consumer is migrated, render the application without AppProvider and remove the provider-only translations, routing adapter, feature flags, styles, and tests that no longer have consumers.

Removing AppProvider

import {createRoot} from 'react-dom/client';

import {App} from './App';

createRoot(document.getElementById('app')!).render(<App />);

import {AppProvider} from '@shopify/polaris';

import enTranslations from '@shopify/polaris/locales/en.json';

import {createRoot} from 'react-dom/client';

import {App} from './App';

import {RouterLink} from './RouterLink';

createRoot(document.getElementById('app')!).render(

<AppProvider

i18n={enTranslations}

linkComponent={RouterLink}

<App />

</AppProvider>,

);

Polaris web components app root

import {createRoot} from 'react-dom/client';

import {App} from './App';

createRoot(document.getElementById('app')!).render(<App />);

Polaris React

import {AppProvider} from '@shopify/polaris';
import enTranslations from '@shopify/polaris/locales/en.json';
import {createRoot} from 'react-dom/client';

import {App} from './App';
import {RouterLink} from './RouterLink';

createRoot(document.getElementById('app')!).render(
  <AppProvider
    i18n={enTranslations}
    linkComponent={RouterLink}
  >
    <App />
  </AppProvider>,
);

Removing the wrapper shouldn't change the rendered page. If the page changes, identify the remaining dependency instead of recreating AppProvider around Polaris web components.

Anchor to Removed propertiesRemoved properties

Anchor to i18ni18n

The i18n property supplied translations for text owned by Polaris React components. Remove Polaris locale imports after no Polaris React component consumes them.

Keep the app's own localization system and translated product copy. Test translated routes before deleting locale data so app-owned strings aren't removed with Polaris strings.

Anchor to linkComponentlinkComponent

The linkComponent property adapted links rendered inside Polaris React components to an app router. Polaris web components use real href values on components such as s-link and s-button.

Preserve normal link behavior, including modified clicks, opening in a new tab, copied URLs, and browser back and forward navigation. Keep router integration at the application routing layer rather than introducing a provider solely to adapt component links.

Anchor to themetheme

Remove the theme property and any theme value imported only for AppProvider. Polaris web components own their supported appearance.

Audit app-owned CSS separately. Don't copy internal Polaris React classes, CSS variables, or theme context into the migrated UI.

Anchor to featuresfeatures

Remove features values that only toggled Polaris React behavior. If a flag also controls app logic, move that flag to the app's own configuration before removing the provider.

Don't pass old Polaris feature flags through a compatibility context.

Anchor to childrenchildren

Render the existing application tree directly. If a non-embedded route still uses Polaris React, keep a clearly bounded AppProvider around that legacy route until it is migrated; don't keep it around the completed embedded app by default.

Anchor to Remove provider-managed behaviorRemove provider-managed behavior

AppProvider also initialized behavior used internally by Polaris React:

Internationalization and theme contexts.
Link adaptation.
Portal, focus, ephemeral-presence, scroll-lock, and sticky managers.
Media-query context and Polaris React global styles.

Migrate overlays, sticky content, and other dependent components before removing the provider. Polaris web component overlays manage their own focus, portal, and scroll behavior. Custom overlays or sticky regions remain app-owned and need their own accessible implementation.

Remove stylesheet imports and app CSS that target .Polaris-* classes after their final consumer is gone. Don't copy the provider's internal root classes or scrollbar variables into the new app shell.

Anchor to Remove AppProvider safelyRemove AppProvider safely

Search the mounted application tree for imports from @shopify/polaris.
Migrate remaining components that consume provider context, including overlays and links.
Remove AppProvider from test render helpers only after the corresponding production tree no longer needs it.
Render the application directly and remove unused provider props, locale imports, link adapters, flags, and styles.
Run the full application test suite and production build.
Remove @shopify/polaris only after no other route or package in scope imports it.

If public, authentication, or standalone routes share the repository and still use Polaris React, document that boundary and keep the dependency until those routes are migrated.

Anchor to Test the removalTest the removal

Test every migrated route with direct navigation, browser history, and modified link clicks.
Exercise modals, popovers, focus restoration, scroll locking, and sticky content.
Test translated content and a locale with longer strings.
Confirm no .Polaris-* selectors, provider contexts, or Polaris locale imports remain in the migrated tree.
Check the browser console for missing context, custom-element, or stylesheet errors.
Verify unit-test helpers no longer add AppProvider silently.
Run a production build after removing the package and stylesheet imports.

Anchor to Related guidanceRelated guidance

Was this page helpful?