How to Deploy & Use mozilla/metrics-graphics

# MetricsGraphics Deployment & Usage Guide

A concise guide to installing, developing, and deploying the MetricsGraphics data visualization library.

## 1. Prerequisites

- **Node.js** 16+ (LTS recommended)
- **Yarn Classic** (1.x) - [Installation Guide](https://classic.yarnpkg.com/lang/en/docs/install/)
- **Git**

Verify installation:
```bash
node --version  # v16.0.0 or higher
yarn --version  # 1.x.x

2. Installation

For Library Development

Clone the monorepo and install workspace dependencies:

git clone https://github.com/metricsgraphics/metrics-graphics
cd metrics-graphics
yarn install

For Project Usage

Install the published package (lightweight, ~15kB gzipped):

npm install mg2
# or
yarn add mg2

3. Configuration

No environment variables or external configuration files are required for basic usage.

TypeScript Configuration

The library includes TypeScript definitions. Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "moduleResolution": "node"
  }
}

4. Build & Run

Development Mode

The project uses Yarn Workspaces with two main packages. Run both simultaneously:

Terminal 1 - Library Development:

cd packages/lib
yarn dev

Terminal 2 - Examples/Documentation:

cd packages/examples
yarn dev

The examples site will hot-reload when you modify library code.

Production Build

Build the library for distribution:

cd packages/lib
yarn build

This generates optimized bundles in packages/lib/dist/.

Basic Usage Example

Create an HTML container:

<div id="chart"></div>

Mount a chart:

import LineChart from 'mg2'  // or 'metrics-graphics'

new LineChart({
  data: yourDataArray,
  width: 600,
  height: 200,
  target: '#chart',
  area: true,
  xAccessor: 'date',
  yAccessor: 'value'
})

5. Deployment

Publishing the Library (Maintainers)

From the library package directory:

cd packages/lib
yarn build
npm version [patch|minor|major]
npm publish

Deploying Examples/Documentation

The examples package builds to static files suitable for hosting on:

• Netlify (currently used for the official site)
• Vercel
• GitHub Pages

Build command:

cd packages/examples
yarn build

Deploy directory: packages/examples/dist (or equivalent build output)

Integration in Production Apps

Since MetricsGraphics is a client-side library:

1. Static Sites: Import normally; bundle with Vite/Webpack/Rollup
2. SSR (Next.js/Nuxt): Import dynamically or ensure D3 dependencies are client-side only:

   import('mg2').then(({ default: LineChart }) => {
     // Initialize chart
   })
   

6. Troubleshooting

Yarn Workspace Issues

Problem: Dependencies not linking between packages
Solution:

yarn install --force
# or
yarn install --check-files

D3 Dependency Errors

Problem: Cannot find module 'd3' or TypeScript errors
Cause: D3 is a peer dependency
Solution:

npm install d3
npm install --save-dev @types/d3  # For TypeScript projects

Port Conflicts in Development

Problem: EADDRINUSE when running yarn dev
Solution: The examples dev server runs on a specific port (check packages/examples/package.json). Kill existing processes:

lsof -ti:3000 | xargs kill -9  # Replace 3000 with actual port

TypeScript Compilation Errors

Problem: TS2307: Cannot find module 'metrics-graphics'
Solution: Ensure module resolution is set correctly in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Brush/Interaction Not Working

Problem: Tooltip or brush interactions unresponsive
Check: Ensure the target DOM element exists and has dimensions before mounting:

// Ensure element is in DOM and visible
if (document.querySelector('#chart').offsetHeight > 0) {
  new LineChart({ target: '#chart', ... })
}