v3.0.0

To Existing Project

It describes how to integrate Mantis theme to existing project.

Many times, our customers do not want to start using Mantis in a new project instead they wanted to apply Mantis themes to their existing ones. This seems to be challenging for them as every project has different architecture and structure. To resolve this, we have picked one free project from MUI itself and tried to integrate 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

      2. DevDependencies

  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.

PreviousComparisonNextComponents

Last updated