Skip to main content

v5.0.0 to v6.0.0

This guide helps you migrate your project from v5.0.0 to v6.0.0. We have upgraded the template to Next.js 16, React 19, Material-UI 7 and TailwindCSS 4, and there are some important changes that you need to incorporate in your project.

Before proceeding, it is strongly recommended to compare your package.json with the new package.json to ensure all dependencies are updated.

For additional details on updating the template, please refer to the How to update this template? guide.

Next.js v16 Changes​

The project has been upgraded to Next.js 16, which introduces several significant updates. For comprehensive guidance, please refer to the official migration guide. Key modifications applied in this template include:

  1. Next.js has revised the lang parameter type from Locale to string. Accordingly, update all relevant layout and route files as follows:
    params: Promise<{ lang: Locale }> → params: Promise<{ lang: string }>

    Furthermore, replace usages of [params.lang] with [lang as Locale], or define the lang as shown below and use [lang] directly without type assertion:

    const lang: Locale = i18n.locales.includes(params.lang as Locale)
        ? (params.lang as Locale)
        : i18n.defaultLocale

  2. In your next.config.ts file, update the route configuration accordingly:

    - source: '/((?!(?:en|fr|ar|front-pages|favicon.ico)\\b)):path',
    + source: '/:path((?!en|fr|ar|front-pages|images|api|favicon.ico).*)*'

MUI v7 Changes​

MUI is upgraded to v7 in this template. Please follow the official upgrade guide for more information.

  1. Material-UI v7 deprecates the Grid2 component and replaces it with Grid. All occurrences of Grid2 should therefore be updated to Grid.

    - import Grid from '@mui/material/Grid2'
    + import Grid from '@mui/material/Grid'

  2. Please add the forceThemeRerender property in the src/components/theme/index.tsx file as shown below. This ensures that theme variables are recalculated correctly when switching between light and dark modes.

    <ThemeProvider
      theme={theme}
      forceThemeRerender // Add this line
      ...
    >

Tailwind v4 Changes​

Tailwind CSS v4.0 introduces significant changes to project configuration. Deprecated utility classes have been replaced with their updated equivalents. For a complete list of changes, please refer to the official upgrade guide.

  1. All configuration is now handled directly within CSS, removing the need for the tailwind.config.ts file. All customizations should be placed in your global.css file, where Tailwind is imported. This update centralizes all styling-related configuration in one location.

    @layer theme, base, components, utilities;
    @import "tailwindcss/theme.css" layer(theme) important;
    @import "tailwindcss/utilities.css" layer(utilities) important;
    @plugin 'tailwindcss-logical';

    @theme {
      --radius-none: 0px;
      --radius-xs: var(--mui-shape-customBorderRadius-xs);
      --radius-sm: var(--mui-shape-customBorderRadius-sm);
      --radius: var(--mui-shape-customBorderRadius-md);
      --radius-md: var(--mui-shape-customBorderRadius-md);
      --radius-lg: var(--mui-shape-customBorderRadius-lg);
      --radius-xl: var(--mui-shape-customBorderRadius-xl);
      --radius-2xl: 0.75rem;
      ... // Add other customizations here
    }

    ... // Add other layers or customizations here

    You may now safely delete the tailwind.config.ts file, as it is no longer required. Any configuration previously defined in src/@core/tailwind/plugin.ts must be migrated into the global.css file.

    With this CSS-first approach, you can configure design tokens, define custom utilities, create variants, and more—effectively covering the full functionality that was formerly managed through tailwind.config.js.

  2. Please update the postcss.config.mjs file to the following:

    const config = {
      plugins: ['@tailwindcss/postcss']
    }

    export default config

ESLint Configuration Changes​

The ESLint configuration has been updated due to the deprecation of @typescript-eslint/ban-types. Please compare and replace your existing .eslintrc.ts file with the updated configuration provided in the template.
Additionally, the related script in package.json has been updated; you may reference the new package.json for the correct command.

Tiptap Editor v3 Changes​

The Tiptap editor has been upgraded to v3, which includes breaking changes. For detailed information, please review the official upgrade guide. Replace the following files in your project with the updated versions provided in the template:

  • src/views/apps/ecommerce/products/add/ProductInformation.tsx
  • src/views/apps/email/ComposeMail.tsx
  • src/views/apps/email/MailDetails.tsx