iView UI Toolkit - Deployment & Usage Guide

A comprehensive guide for installing, configuring, and deploying applications using iView, a high-quality Vue.js 2.0 UI component library.

1. Prerequisites

Before starting, ensure you have the following installed:

Node.js: >= 8.0.0 (LTS recommended)
npm: >= 5.0.0 or Yarn >= 1.0.0
Vue.js: 2.x (iView 3.x requires Vue 2.0+)
Vue CLI: 3.0+ (recommended for new projects)

Browser Support Requirements:

Modern browsers (Chrome, Firefox, Safari, Edge)
IE9+ (most components; some features require IE10+)

2. Installation

Choose one of the following methods based on your project needs:

Method A: Vue CLI Plugin (Recommended for New Projects)

If using Vue CLI 3 or 4:

vue create my-iview-app
cd my-iview-app
vue add iview

This automatically configures iView with babel-plugin-import for on-demand component loading.

Method B: NPM/Yarn in Existing Project

# Using npm
npm install iview --save

# Using yarn
yarn add iview

Method C: Starter Kit (iview-project)

For a pre-configured example project:

git clone https://github.com/iview/iview-project.git
cd iview-project
npm install

Method D: CDN (Global Usage)

For prototyping or simple HTML pages:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://unpkg.com/iview/dist/styles/iview.css">
</head>
<body>
    <div id="app"></div>
    <script src="https://unpkg.com/vue/dist/vue.min.js"></script>
    <script src="https://unpkg.com/iview/dist/iview.min.js"></script>
</body>
</html>

3. Configuration

Basic Setup (Full Import)

In your main.js or entry file:

import Vue from 'vue';
import iView from 'iview';
import 'iview/dist/styles/iview.css';
import App from './App.vue';

Vue.use(iView);

new Vue({
  el: '#app',
  render: h => h(App)
});

On-Demand Import (Recommended for Production)

Install babel-plugin-import:

npm install babel-plugin-import --save-dev

Update .babelrc or babel.config.js:

{
  "plugins": [
    ["import", {
      "libraryName": "iview",
      "libraryDirectory": "src/components"
    }]
  ]
}

Then import components as needed:

import { Button, Slider, Table } from 'iview';

export default {
  components: {
    Button,
    Slider,
    Table
  }
}

Nuxt.js Configuration

Create plugins/iview.js:

import Vue from 'vue';
import iView from 'iview';
import 'iview/dist/styles/iview.css';

Vue.use(iView);

Update nuxt.config.js:

module.exports = {
  plugins: [
    { src: '~/plugins/iview.js', ssr: true }
  ],
  build: {
    transpile: ['iview']
  }
}

TypeScript Support

Install type definitions:

npm install @types/iview --save-dev

Add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["iview"]
  }
}

4. Build & Run

Development Mode

If using the starter kit (iview-project):

npm run dev
# or
npm start

For custom Vue CLI projects:

npm run serve

Production Build

npm run build

This generates optimized assets in the dist/ directory.

Building iView from Source (Contributors)

git clone https://github.com/iview/iview.git
cd iview
npm install
npm run build

Available scripts (typical):

npm run dev - Development server with hot reload
npm run build - Build library for production
npm run build:dist - Build distribution files
npm run test - Run test suite

5. Deployment

Static Hosting (SPA)

For standard Vue.js single-page applications:

Build the project:
```
npm run build
```
Deploy the dist/ directory to:
- Netlify: Drag and drop dist/ folder or use CLI
- Vercel: vercel --prod (ensure dist is set as output directory)
- GitHub Pages: Push dist/ to gh-pages branch
- AWS S3: Sync dist/ with S3 bucket configured for static hosting

Important: Configure rewrite rules to serve index.html for all routes (SPA fallback).

Server-Side Rendering (Nuxt.js)

For Nuxt.js applications using iView:

npm run build
npm start

Deploy to:

Vercel: Zero-config SSR support
Heroku: Use Node.js buildpack
Docker: Multi-stage build with node:alpine

Example Dockerfile:

FROM node:14-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Electron Applications

Package with electron-builder:

npm install electron-builder --save-dev
npm run electron:build

Output will be in dist_electron/ for distribution.

CDN Deployment

When using the CDN version, ensure assets are cached properly:

<!-- Version-locked for production -->
<link rel="stylesheet" href="https://unpkg.com/iview@3.5.4/dist/styles/iview.css">
<script src="https://unpkg.com/iview@3.5.4/dist/iview.min.js"></script>

6. Troubleshooting

Styles Not Loading

Issue: Components appear unstyled or layout is broken.

Solution: Ensure CSS is imported in your entry file:

import 'iview/dist/styles/iview.css';

Or if using less-loader:

import 'iview/src/styles/index.less';

IE9/10 Compatibility

Issue: App breaks in Internet Explorer.

Solution: Install polyfills:

npm install babel-polyfill --save

Import in main.js (before Vue):

import 'babel-polyfill';
import Vue from 'vue';

Configure vue.config.js for transpilation:

module.exports = {
  transpileDependencies: ['iview']
}

Large Bundle Size

Issue: Vendor bundle too large.

Solution: Use on-demand loading with babel-plugin-import (see Configuration section). Avoid importing the entire library:

// Avoid this in production:
import iView from 'iview'; // Imports everything
Vue.use(iView);

SSR Hydration Errors

Issue: Mismatch between server and client HTML when using Nuxt.js.

Solution: Ensure iView plugins are registered with ssr: true and avoid accessing browser APIs in created() hooks.

Icon Font Not Displaying

Issue: Icons show as squares or empty.

Solution: Verify font files are being loaded. If using custom webpack config, ensure file-loader handles font files:

{
  test: /\.(woff2?|eot|ttf|otf)(\?.*)?$/,
  loader: 'url-loader',
  options: {
    limit: 10000,
    name: 'fonts/[name].[hash:7].[ext]'
  }
}

Version Conflicts

Issue: "Vue is not defined" or multiple Vue instances.

Solution: Ensure Vue is externalized in webpack when building library:

externals: {
  vue: 'Vue'
}

For support, visit Gitter Chat or Stack Overflow with [iview-ui] tag.

How to Deploy & Use iview/iview