To Existing Project

It describes how to integrate Mantis theme to existing project.

Frequently, our customers express a desire to integrate Mantis themes into their existing projects rather than initiating new ones. This presents a unique challenge since each project comes with its own distinct architecture and structure. In order to address this challenge, we have taken the initiative to select a free project from MUI and have undertaken the task of seamlessly integrating Mantis into it.

Existing Project that we picked:

Dashboard: https://mui.com/material-ui/getting-started/templates/

Live Preview: https://mui.com/material-ui/getting-started/templates/dashboard/

In this guide, we are going to apply the Mantis theme to the above project step by step.

Project structures vary widely, making a universal guide unfeasible. To assist, we've selected an MUI project as a foundational reference. Clients can leverage this as a starting point, customizing integration as necessary. However, please note this isn't a strict template to be replicated.

Steps to follow

1. Backup Your Project: Before making any changes, create a backup of your existing project to ensure you can revert back in case anything goes wrong.

2. Install dependencies and development dependencies: To install a list of dependencies and devDependencies in an existing project using npm or Yarn, follow these steps:

   1. Open a Terminal: Navigate to the root directory of your project using a terminal or command prompt.

   2. Review package.json: Before adding dependencies, it's a good idea to review your project's package.json file to check for any existing dependencies and devDependencies. You can either move or add the following packages:

      1. Dependencies

         • @ant-design/colors

         • @ant-design/icons

         • @emotion/react

         • @emotion/styled

         • @mui/icons-material

         • @mui/lab

         • @mui/material

         • lodash

      2. DevDependencies

         • @types/lodash

3. Migrate theme to your project: The following files/folders need to move to your project to achieve Mantis theming

   1. Context

      We need to move ConfigContext to have theme property context like theme color, font, etc.

      • Source Path: full-version\src\contexts\ConfigContext.tsx

      • Destination Path: src\contexts\ConfigContext.tsx

   2. Hooks

      Hooks can use to access values of the theme and localStorage throughout the project. Two hooks needed to be copied.

      • Source Path:

        • full-version\src\hooks\useConfig.ts

        • full-version\src\hooks\useLocalStorage.ts

      • Destination Path:

        • src\hooks\useConfig.ts

        • src\hooks\useLocalStorage.ts

   3. Themes

      This is the main directory to achieve themes. You need to copy the entire directory to the destination.

      • Source Path: full-version\src\themes

      • Destination Path: src\themes

   4. Types

      Types related to the theme needed to move as well to avoid errors in the compilation. Not all types are needed but only the following:

      • Source Paths:

        • full-version\src\types\overrides - Entire directory

        • full-version\src\types\config.ts

        • full-version\src\types\extended.ts

        • full-version\src\types\theme.ts

      • Destination Paths:

        • src\types\overrides

        • src\types\config.ts

        • src\types\extended.ts

        • src\types\theme.ts

   5. Utility

      To get color variants and custom shadows, the utility provides functions.

      • Source Path:

        • full-version\src\utils\getColors.ts

        • full-version\src\utils\getShadow.ts

      • Destination Path:

        • src\utils\getColors.ts

        • src\utils\getShadow.ts

   6. Config

      The default configuration of the theme.

      • Source Path: full-version\src\config.ts

      • Destination Path: src\config.ts

   7. TSConfig

      Configuration related to typescript. Mainly to set 'baseUrl' but you can also copy an entire file if you need.

      • Source Path: tsconfig.json

      • Destination Path: tsconfig.json

4. Setup App page: Once you migrate the files mentioned in the above steps, you need to set up the App component so that linking can be set between the theme and the app. Do the following in the destination project:

App.tsx

import ThemeCustomization from 'themes';
import Dashboard from './dashboard/Dashboard';

function App() {
  return (
    <ThemeCustomization>
      <Dashboard />
    </ThemeCustomization>
  );
}

export default App;

That's all you need to follow and your project is ready with the Mantis theme.

---

Following is the live preview for an existing project where we followed the above steps and applied a theme, you can compare it with the existing theme and see the differences:

Live Preview (With Mantis Theme): https://mantisdashboard.io/react/existing_theme_integration/

Live Preview (Without Mantis Theme): https://mui.com/material-ui/getting-started/templates/dashboard/

You can see that app bar and a few other changes have been visible there. We have also added some additional components on the main page to showcase the Mantis theme on that component.

Comparison between Applied Mantis Theme (Left) & default theme (Right side)

Applied Mantis theme on components