How to Deploy & Use morrisjs/morris.js

# Morris.js Deploy and Usage Guide

A comprehensive guide for building, developing, and deploying Morris.js, a CoffeeScript charting library for time-series line, bar, area, and donut charts.

## 1. Prerequisites

### Runtime Dependencies (for end users)
- **jQuery** >= 1.7 (older versions may work but not recommended)
- **Raphael.js** >= 2.0 (SVG/VML graphics library)

### Development Dependencies (for contributors)
- **Node.js** (recommend installing via [nvm](https://github.com/creationix/nvm))
- **npm** (comes with Node.js)
- **Git**

### Global npm packages
```bash
npm install -g grunt-cli bower

2. Installation

For Development (Contributors)

Clone the repository and install dependencies:

git clone https://github.com/morrisjs/morris.js.git
cd morris.js
npm install
bower install

Important: This is a CoffeeScript project. Always edit files in the lib/ directory (.coffee files), not the compiled JavaScript files in the project root.

For Production Use (End Users)

Choose one of the following methods:

Via Bower:

bower install morris

Manual Download: Download morris.js or morris.min.js from the repository root (these are the compiled artifacts).

CDN: Include dependencies and Morris.js in your HTML:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.css">

3. Configuration

Chart Configuration

Morris.js requires a container element and data array. Basic configuration structure:

Morris.Line({
  element: 'my-chart-element',  // ID of container div
  data: [
    { year: '2020', value: 20 },
    { year: '2021', value: 10 },
    { year: '2022', value: 5 }
  ],
  xkey: 'year',           // X-axis field
  ykeys: ['value'],       // Y-axis field(s)
  labels: ['Value']       // Label for hover/tooltip
});

Build Configuration

Build settings are managed via Gruntfile.js (located in project root). Key tasks:

• grunt coffee - Compiles .coffee files to .js
• grunt uglify - Minifies to morris.min.js
• grunt test - Runs test suite
• grunt (default) - Compiles, minifies, and tests

No environment variables or API keys are required for this library.

4. Build & Run

Development Workflow

Compile CoffeeScript and run tests:

grunt

Watch for changes during development:

grunt watch  # If configured, or manually re-run grunt

Testing

Note: The test suite includes perceptual diff tests for rendering regression detection. Due to font rendering differences between platforms, these tests only pass on macOS/OS X. Linux/Windows developers should expect perceptual diff test failures.

Run specific test tasks:

grunt test        # Full test suite
grunt coffee      # Compile only
grunt uglify      # Minify only

Local Examples

The examples/ directory contains HTML demonstrations. Serve the project root with any static server:

# Using Python 3
python -m http.server 8000

# Using Node.js http-server (if installed globally)
http-server -p 8000

Then navigate to http://localhost:8000/examples/ to view charts.

5. Deployment

Library Distribution

Since Morris.js is a client-side library, "deployment" means distributing the built artifacts:

For Bower Registry: Ensure bower.json is updated with version bumps, then tag releases:

git tag v0.5.1
git push origin --tags

For Manual Integration:

1. Run grunt to ensure compiled files are up-to-date
2. Copy these files to your production project:
   • morris.js (development)
   • morris.min.js (production)
   • morris.css (styles)

Web Application Integration:

<div id="chart" style="height: 250px;"></div>
<script>
  Morris.Bar({
    element: 'chart',
    data: [
      { device: 'iPhone', geekbench: 136 },
      { device: 'iPhone 3G', geekbench: 137 },
      { device: 'iPhone 3GS', geekbench: 275 }
    ],
    xkey: 'device',
    ykeys: ['geekbench'],
    labels: ['Geekbench'],
    barColors: ['#0B62A4']
  });
</script>

Hosting Platforms

Suitable platforms for demo sites or documentation:

• GitHub Pages: Ideal for the project documentation site (currently hosted at morrisjs.github.com/morris.js/)
• Netlify/Vercel: Connect to GitHub repo for automatic deployments of example pages
• CDNjs: Submit PR to cdnjs/cdnjs repo for CDN distribution

6. Troubleshooting

Build Issues

Problem: grunt command not found Solution: Install grunt-cli globally: npm install -g grunt-cli

Problem: Bower dependencies not found Solution: Run bower install in project root (separate from npm install)

Problem: Changes to .js files are overwritten Solution: Edit .coffee files in lib/ directory only. The root .js files are build artifacts.

Test Failures

Problem: Perceptual diff tests fail on Linux/Windows Solution: This is expected due to font rendering differences. These tests are designed to pass only on macOS. If developing on other platforms, focus on unit test results or run tests in a macOS environment.

Problem: Travis CI build failures Solution: Ensure CoffeeScript files compile without errors: grunt coffee. Check that all tests pass locally on macOS before pushing.

Runtime Issues

Problem: Charts not rendering (blank div) Solution:

• Verify jQuery and Raphael.js are loaded before Morris.js
• Check browser console for "Raphael is not defined" errors
• Ensure the container element has explicit height/width

Problem: Time-series labels incorrect Solution: Morris.js expects date strings in formats like 2012-01-01 or ISO8601. Ensure your X-key data is parseable by JavaScript Date objects.

Problem: Hover tooltips not appearing Solution: Check hideHover option is not set to 'always'. Verify CSS file is loaded and not being overridden by other stylesheets.

Development Notes

• Node.js version: If using nvm, ensure you're on a stable Node.js version (project tested on older Node versions; very new Node versions may have compatibility issues with old Grunt plugins)
• CoffeeScript syntax: Remember CoffeeScript is whitespace-sensitive. Use 2-space indentation consistently.
• Contribution workflow: Fork → Edit .coffee files → Add tests → Run grunt → Submit PR (do not commit compiled .js files, maintainers will rebuild)