Migration Guide

June 24, 2024 · View on GitHub

Migrating to V3 and V4

V3 was entirely re-written with minimal API changes. V4 optimises V3 by minor refactors.

  • No more cookies.
  • You no longer need to use NextJsSSGThemeSwitcher, NextJsServerTarget, or ServerSideWrapper.
  • Flash of Unstyled Content (FOUC) is now handled by an injected script.
  • If you have been using these components, they will have no effect. We recommend removing them.
  • There is no need to use sibling selectors. Without NextJsSSGThemeSwitcher or NextJsServerTarget, you are free to use any target, whether as a wrapper or a sibling.

Breaking Changes - these should only affect a very small fraction of library users

  • ForceColorScheme and ForceTheme are no longer exported from nextjs-themes or nextjs-themes/client. Use nextjs-themes/force-color-scheme or nextjs-themes/force-theme instead.
  • The class names for ColorSwitch have been shortened.

Migrating from V1 to V2

Major Changes

  • Commit 6f17cce: Added additional CSS combinations to ensure seamless support for Tailwind.

    • No changes are required for client-side code as [data-theme=] selectors function as before.
    • If you are using ServerSideWrapper, NextJsServerTarget, or NextJsSSGThemeSwitcher, you need to convert forcedPages elements to objects shaped like { pathMatcher: RegExp | string; props: ThemeSwitcherProps }.
    • Use resolvedColorScheme for more robust dark/light/system modes.
    • Use combinations of [data-th=""] and [data-color-scheme=""] for dark/light theme variants.
    • Use [data-csp=""] to style based on color scheme preference.

Minor Changes

  • Support for custom themeTransition.

    • Provide the themeTransition prop to the ThemeSwitcher component to apply a smooth transition when changing the theme.
    • Use setThemeSet to set lightTheme and darkTheme together.

Motivation

For server-side syncing, cookies and headers are required. This means that this component and its children cannot be static and will be rendered server-side for each request. To avoid the wrapper, only the NextJsSSGThemeSwitcher will be rendered server-side for each request, while the rest of your app can be served statically.

Consider the following when migrating to V2:

  • No changes are required for projects not using the Next.js app router or server components, aside from updating the cookies policy if needed.
  • Persistent storage now uses cookies instead of localStorage. (You might need to update your cookies policy accordingly.)
  • We have introduced NextJsSSGThemeSwitcher in addition to ServerSideWrapper for Next.js. You no longer need to use a wrapper component that breaks static generation and forces SSR.
  • For more details, visit With Next.js app router (Server Components).

Migrating from V0 to V1

  • defaultDarkTheme has been renamed to darkTheme.
  • setDefaultDarkTheme has been renamed to setDarkTheme.
  • defaultLightTheme has been renamed to lightTheme.
  • setDefaultLightTheme has been renamed to setLightTheme.

with 💖 by Mayank Kumar Chaudhari