Table of Contents

• Introduction
• Features
• Installation
• Usage
  • Create new project
  • Generate theme file to an existing project
  • Validate theme file in existing project
  • Component Scaffolding
• Supported MUI components

Material-UI CLI: Streamlining Your Development Workflow

The Material-UI CLI is a powerful command-line interface tool designed to significantly streamline and enhance the development process with Material-UI, a renowned React UI framework. This CLI tool simplifies the initialization of new projects, the generation and validation of theme files, and the scaffolding of popular Material-UI components, thereby allowing developers to focus on creating exceptional user interfaces without getting bogged down by the setup and configuration process.

✨ Comprehensive Feature Set

• Project Initialization: Kickstart your development with a new React, Vite or Next.js project, pre-configured with Material-UI dependencies, allowing for a smooth and rapid setup.
• Theme Generation: Easily generate a theme file for your project, customizable with primary, secondary, error, warning, info, and success color options, laying the foundation for a consistent design system.
• Theme Validation: Ensure your theme file adheres to Material-UI's theming guidelines, with options to validate palette, typography, spacing, breakpoints, and transitions, thus guaranteeing a polished and error-free UI.
• Component Scaffolding: Choose from a wide array of popular Material-UI components to scaffold into your project, organized neatly within your project structure, saving you the hassle of manual setup and configuration.

📦 Installation

npm i -g material-cli

🚀 Usage

1. 🦾 Create new project.

To initialize a new project, first, navigate to the desired folder, then:

material-cli project-init

You will be then prompted with questions to select:

• Project name
• Your preferred tool: React, Vite or Next.js
• Your preferred architecture: Monorepo or Polyrepo
• Popular MUI components you want to scaffold to your project.

If everything proceeded smoothly, you'll receive a confirmation message indicating that your project setup is complete. Navigate to the project directory and execute the reccomended script command.

Initializing a new project with the MUI CLI offers several advantages:

• ⚡ Choose your preffered tool to use between CRA, Vite and Next.js.
• 🌐 Choose your preffered architecture between Monorepo and Polyrepo.
• 🚀 Experience faster project initialization for CRA over the conventional CRA Command method.
• 📦 Automatically installs all Material UI-related dependencies, including MUI icons.
• ✅ Allows selection of specific Material UI components to scaffold into your project.
• ⚙️ Automatically generates a theme file.
• 🎨 Comes with pre-configured Material UI theming for both React, Vite and Next.js projects.
• 🌟 Lets you focus more on development rather than setup.

The downside of using MUI CLI to initialize your project includes:

• ⚠️ The scaffolded MUI components are written in JavaScript, which could be a downside for those using TypeScript.

The MUI CLI team is actively exploring the best ways to address these issues promptly to facilitate smoother development.

2. ⚙️ Generate theme file to an existing project.

Ensuring adherence to the correct MUI theming guidelines can sometimes be challenging. With MUI CLI, you can effortlessly generate a theme file that you can then customize to your preferences. To generate a theme file for your existing project, simply execute the following command:

material-cli theme-init [options]

The following options can be passed to the command:

| Option | Description | | ---------------------------- | ---------------------- | | -p, --primary (optional) | Primary color option | | -s, --secondary (optional) | Secondary color option | | -e, --error (optional) | Error color option | | -w, --warning (optional) | Warning color option | | -i, --info (optional) | Info color option | | -x, --success (optional) | Success color option |

The theme.js file will be generated under src > Theme folder in your project. Note that only palette options can be passed as option.

3. 🔍 Validate theme file in existing project.

You can easily inspect your theme file to identify any potential errors or warnings that might have been overlooked. To inspect your theme file, simply execute the following command:

material-cli theme-validate [options]

The following options can be passes to the command:

| Option | Description | | ------------------------------- | --------------------------------------- | | -p, --palette (optional) | Validate palette in your theme file | | -t, --typography (optional) | Validate typography in your theme file | | -s, --spacing (optional) | Validate spacing in your theme file | | -b, --breakpoints (optional) | Validate breakpoints in your theme file | | -tr, --transitions (optional) | Validate transitions in your theme file | | --path (optional) | Path to your theme file | | --ignore-warn (optional) | dont show warning |

If the path option is not provided, you will be prompted with a question to specify the path to your theme file.

If no other options are passed, all properties in your theme will be validated by default.

Upon inspecting your theme file, any potential errors will be displayed in your console, along with any potential warnings. To disregard warnings, you can include the --ignore-warn flag in the command.

[!NOTE] The contents of the theme file should be a function that returns the theme object. If the theme file is not a function, an error will occur. This is one of the limitations we are working to resolve.

The theme file can have the following format:

const themeConfig = () => ({
  // Theme contents
});

4. ✂️ Component Scaffolding

Simplify your development workflow with automated component creation. The MUI CLI allows you to quickly scaffold reusable components into your project, accelerating development and ensuring consistency throughout your application.

These components adhere to MUI guidelines and are highly customizable. Explore all supported components here

To scaffold a specific component into your project, execute the following command:

material-cli install <componentName>

Upon running this command, you'll be prompted to specify the path where you want your component to be scaffolded. The default path is scr/components/<componentsName>

🧩 Supported MUI components

Below is a list of supported components, categorized for ease of understanding and integration.

| Component | Description | Category | | ---------------------------------- | ------------------------------------------------------------------------ | ----------- | | App Bar | Popular Material UI component for app bars. | Surfaces | | AutoComplete | Material UI component providing autocomplete functionality. | Inputs | | Data Grid | Material UI component for displaying data grids. | DataDisplay | | Dates | Material UI component for selecting dates. | Inputs | | Select | Material UI component for selecting options from a list. | Inputs | | Tabs | Material UI component for organizing content into tabs. | Navigation | | Text Field | Material UI component for text input fields. | Inputs | | Alert | Material UI component for displaying alerts. | Feedback | | Dialog | Material UI component for displaying dialog boxes. | Feedback | | Linear Progress | Material UI component for indicating progress linearly. | Feedback | | Snackbar | Material UI component for displaying snackbars. | Feedback | | Accordion | Material UI component for creating accordion-style content. | Surfaces | | Android Switch | Material UI component for switches styled like those on Android devices. | Switch | | Ant Switch | Material UI component for switches styled like those in Ant Design. | Switch | | iOS Switch | Material UI component for switches styled like those on iOS devices. | Switch | | MUI Switch | Material UI default switch component. | Switch |

Components are organized under the src/Components directory, with each having its designated folder for easy management and accessibility.