Mint UI Deploy & Usage Guide

Comprehensive guide for integrating and deploying the Mint UI mobile component library for Vue.js.

Prerequisites

Node.js: v6.0+ (LTS recommended)
Package Manager: npm (v3+) or Yarn
Vue.js: 2.0+ (for Mint UI v2) or 1.x (for Mint UI v1)
Build Tool: Webpack, Vue CLI, or Vite (for bundling)

Installation

NPM Installation

For Vue 2.0 projects (recommended):

npm install mint-ui --save

For Vue 1.x legacy projects:

npm install mint-ui@1 --save

CDN Installation

Include directly in HTML without build tools:

Via unpkg (NPMCDN):

<link rel="stylesheet" href="https://unpkg.com/mint-ui/lib/style.css">
<script src="https://unpkg.com/mint-ui/lib/index.js"></script>

Via RawGit:

<link rel="stylesheet" href="https://cdn.rawgit.com/ElemeFE/mint-ui/master/lib/style.css">
<script src="https://cdn.rawgit.com/ElemeFE/mint-ui/master/lib/index.js"></script>

Configuration

Full Import (Global Registration)

Import all components in your main entry file:

import Vue from 'vue';
import Mint from 'mint-ui';
import 'mint-ui/lib/style.css';

Vue.use(Mint);

On-Demand Import (Tree Shaking)

Install the Babel plugin for automatic modular imports:

npm install babel-plugin-component --save-dev

Configure .babelrc:

{
  "plugins": [
    "other-plugin",
    ["component", [
      {
        "libraryName": "mint-ui",
        "style": true
      }
    ]]
  ]
}

Import specific components in your code:

import { Cell, Checklist } from 'mint-ui';

Vue.component(Cell.name, Cell);
Vue.component(Checklist.name, Checklist);

Note: The Babel plugin automatically imports corresponding CSS files. Without it, manually import styles:

import MtRadio from 'mint-ui/lib/radio';
import 'mint-ui/lib/radio/style.css';
Vue.component(MtRadio.name, MtRadio);

Mobile Viewport Configuration

Ensure proper mobile rendering by adding to your HTML <head>:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no">

Build & Run

Development Setup (Contributing to Mint UI)

Clone and run the documentation/development server:

git clone https://github.com/ElemeFE/mint-ui.git
cd mint-ui
npm install
npm run dev

The dev server typically runs on localhost:8080 or as configured in the project.

Production Build (Consuming Applications)

Vue CLI Projects:

npm run build

Webpack Projects: Ensure your webpack.config.js handles CSS imports:

module: {
  rules: [
    {
      test: /\.css$/,
      use: ['style-loader', 'css-loader']
    }
  ]
}

Deployment

Static Site Deployment

For Vue SPA applications using Mint UI:

Netlify/Vercel:

Build command: npm run build
Publish directory: dist (or your configured output folder)
Ensure _redirects or vercel.json handles SPA routing:
```
/*    /index.html   200
```

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # Gzip compression for Mint UI assets
    gzip on;
    gzip_types text/css application/javascript;
}

Mobile-Specific Considerations

Touch Events: Ensure fastclick or similar is configured to eliminate 300ms delay on mobile browsers
REM/Viewport Units: Mint UI uses px units; configure PostCSS or similar for rem adaptation if needed
Asset Paths: Use relative paths (./) for mobile hybrid apps (Cordova/Capacitor)

Troubleshooting

CSS Not Loading

Symptoms: Components render without styles (unstyled buttons, no layout) Solution:

Verify import 'mint-ui/lib/style.css' is present in your entry file
Check that your build tool is configured to handle .css files
For on-demand imports, ensure babel-plugin-component is properly configured in .babelrc

"Cannot find module 'mint-ui'"

Symptoms: Import errors during build Solution:

Clear npm cache: npm cache clean --force
Delete node_modules and reinstall: rm -rf node_modules && npm install
Verify Vue version compatibility (Vue 2.x requires Mint UI v2, Vue 1.x requires Mint UI v1)

Components Not Registered

Symptoms: [Vue warn]: Unknown custom element: <mt-button> Solution:

When using on-demand imports, ensure you're registering components:

import { Button } from 'mint-ui';
Vue.component(Button.name, Button); // Registers as 'mt-button'

Icons Not Displaying

Symptoms: Icon components show as squares or empty spaces Solution:

Ensure you're importing the complete CSS file which includes icon fonts
Check that font files are being copied to your build output (configure file-loader or url-loader in webpack)

Build Size Too Large

Symptoms: Vendor bundle includes entire library when using only a few components Solution:

Switch to on-demand imports using babel-plugin-component
Verify .babelrc configuration is being applied (check for caching issues)
Use webpack-bundle-analyzer to verify tree-shaking is working

Mobile Browser Compatibility

Symptoms: Layout breaks on specific mobile browsers (UC Browser, WeChat WebView) Solution:

Add appropriate autoprefixer configuration for mobile browsers
Test on target devices; Mint UI targets iOS 6+ and Android 4.0+
Use viewport meta tag strictly as specified in Configuration section

How to Deploy & Use ElemeFE/mint-ui