Installation

Package Installation

Headless Chart can be installed via npm or yarn.

# Using npm
npm install @meursyphus/headless-chart

# Using yarn
yarn add @meursyphus/headless-chart

# Using pnpm
pnpm add @meursyphus/headless-chart

React Project Setup

For React usage, you need to install the @meursyphus/flitter-react package as well.

npm install @meursyphus/headless-chart @meursyphus/flitter-react

Basic Setup

// React project
import { Widget } from '@meursyphus/flitter-react';
import { BarChart } from '@meursyphus/headless-chart';

function App() {
  const chart = BarChart({
    data: {
      labels: ['Jan', 'Feb', 'Mar'],
      datasets: [{
        label: 'Sales',
        data: [100, 200, 150]
      }]
    }
  });

  return <Widget widget={chart} />;
}

Svelte Project Setup

For Svelte, use the @meursyphus/flitter-svelte package.

npm install @meursyphus/headless-chart @meursyphus/flitter-svelte

Basic Setup

<script>
  import Widget from '@meursyphus/flitter-svelte';
  import { BarChart } from '@meursyphus/headless-chart';

  const chart = BarChart({
    data: {
      labels: ['Jan', 'Feb', 'Mar'],
      datasets: [{
        label: 'Sales',
        data: [100, 200, 150]
      }]
    }
  });
</script>

<Widget widget={chart} />

TypeScript Setup

Headless Chart is written in TypeScript and provides complete type support.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Using Type Definitions

import type { ChartData, CustomCartesianChart } from '@meursyphus/headless-chart';

// Data types
const data: ChartData = {
  labels: ['Jan', 'Feb', 'Mar'],
  datasets: [{
    label: 'Sales',
    data: [100, 200, 150]
  }]
};

// Custom component types
const customComponents: CustomCartesianChart = {
  bar: MyCustomBar,
  axis: MyCustomAxis
};

Bundler Configuration

Vite

Vite works out of the box without any special configuration.

// vite.config.js
export default {
  // No special configuration needed
}

Webpack

For Webpack 5:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              '@babel/preset-react',
              '@babel/preset-typescript'
            ]
          }
        }
      }
    ]
  },
  resolve: {
    extensions: ['.js', '.jsx', '.ts', '.tsx']
  }
};

Renderer Selection

Headless Chart supports both SVG and Canvas renderers.

SVG Renderer (Default)

<Widget 
  widget={chart} 
  renderer="svg"  // default
/>

SVG Renderer Advantages:

  • Vector-based, stays crisp when scaled
  • Can be styled with CSS
  • Accessible as DOM elements

Canvas Renderer

<Widget 
  widget={chart} 
  renderer="canvas"
/>

Canvas Renderer Advantages:

  • Better for large datasets
  • Better animation performance
  • Lower memory usage

Development Environment Setup

ESLint Configuration

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    // Configure rules for your project
  }
}

Prettier Configuration

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2
}

Troubleshooting

Module Not Found

# Reinstall node_modules
rm -rf node_modules package-lock.json
npm install

TypeScript Type Errors

# Check TypeScript version
npx tsc --version

# Update to latest version
npm install typescript@latest -D

Next Steps

Once installation is complete, check out the Quick Start guide to create your first chart!