Creating Custom Builds

Highcharts provides a flexible build system that allows you to create custom, optimized bundles containing only the features you need. This reduces file size and improves performance.

Build System Overview

Highcharts uses a modular build system powered by:

TypeScript - Source code in ts/ directory
Gulp - Build orchestration and task automation
@highcharts/highcharts-assembler - Module bundling and assembly
SWC - Fast JavaScript/TypeScript compilation and minification
Webpack - Module bundling for ES modules

Understanding the Module System

Highcharts is structured as ES6 modules that can be assembled in different ways:

// Core modules
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';

// Add specific features
import 'highcharts/es-modules/masters/modules/exporting.src.js';
import 'highcharts/es-modules/masters/modules/boost.src.js';

Build Commands

# Full build
npm run build

# Build only code (faster)
npm run gulp scripts

# Compile TypeScript
npm run gulp scripts-ts

# Compile and minify
npm run gulp scripts-compile

# Watch mode for development
npm run gulp scripts-watch

# Full distribution build
gulp dist

# TypeScript compilation
gulp scripts-ts

# Webpack bundling
gulp scripts-webpack

# CSS compilation
gulp scripts-css

# Minification
gulp scripts-compile

Creating a Custom Build

Identify Required Modules

Determine which Highcharts features you need:

// Minimal chart
const modules = [
  'highcharts',
  'modules/exporting'
];

// Stock chart with indicators
const modules = [
  'highstock',
  'modules/boost',
  'indicators/ema',
  'indicators/macd'
];

Use ES Modules

Import only what you need:

// Custom build with specific features
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';
import 'highcharts/es-modules/masters/modules/exporting.src.js';
import 'highcharts/es-modules/masters/modules/accessibility.src.js';

export default Highcharts;

Bundle with Your Tool

Use your preferred bundler:

// webpack.config.js
module.exports = {
  entry: './src/custom-highcharts.js',
  output: {
    filename: 'highcharts-custom.js',
    library: 'Highcharts',
    libraryTarget: 'umd'
  },
  optimization: {
    minimize: true
  }
};

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    lib: {
      entry: './src/custom-highcharts.js',
      name: 'Highcharts',
      formats: ['es', 'umd']
    },
    rollupOptions: {
      external: [],
      output: {
        globals: {}
      }
    }
  }
});

Build Configuration

TypeScript Configuration

The main TypeScript configuration is in ts/tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES6",
    "moduleResolution": "node",
    "declaration": true,
    "outDir": "../code/es-modules/",
    "strict": true,
    "esModuleInterop": true,
    "stripInternal": true,
    "noEmitOnError": true
  }
}

Compilation Process

Highcharts uses SWC for fast compilation and minification:

// SWC minification options
const options = {
  compress: {},
  format: {
    comments: 'some'
  },
  mangle: true,
  module: true,
  sourceMap: true
};

Using Highcharts Assembler

The @highcharts/highcharts-assembler package builds distributable modules:

const { buildModules } = require('@highcharts/highcharts-assembler/src/build.js');

buildModules({
  base: './js/',
  output: './code/',
  type: 'classic'
});

Tree Shaking with Modern Bundlers

Modern bundlers like Webpack 5, Rollup, and Vite support tree shaking with Highcharts ES modules, automatically removing unused code.

// Only the used parts will be included
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';
import 'highcharts/es-modules/masters/modules/exporting.src.js';

// This creates a smaller bundle automatically

Optimizing Build Size

Use ES Modules

Always prefer ES modules for better tree shaking:

import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';

Import Only Needed Modules

// Bad - imports everything
import Highcharts from 'highcharts';

// Good - imports only what you need
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';
import 'highcharts/es-modules/masters/modules/exporting.src.js';

Enable Compression

Configure your bundler for optimal compression:

// webpack.config.js
module.exports = {
  optimization: {
    minimize: true,
    usedExports: true,
    sideEffects: false
  }
};

Build Products

Highcharts supports building different products:

npm run gulp scripts

npm run gulp scripts --product Stock

npm run gulp scripts --product Maps

npm run dbuild

Custom Build Examples

Minimal Chart Build

// minimal-chart.ts
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';

// Size: ~120KB minified
export default Highcharts;

Stock Chart with Indicators

// stock-with-indicators.ts
import Highcharts from 'highcharts/es-modules/masters/highstock.src.js';
import 'highcharts/es-modules/masters/modules/boost.src.js';
import 'highcharts/es-modules/Stock/Indicators/EMA/EMAIndicator.js';
import 'highcharts/es-modules/Stock/Indicators/MACD/MACDIndicator.js';

// Size: ~250KB minified
export default Highcharts;

Chart with Exporting

// chart-with-export.ts
import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';
import 'highcharts/es-modules/masters/modules/exporting.src.js';
import 'highcharts/es-modules/masters/modules/export-data.src.js';

// Size: ~150KB minified
export default Highcharts;

Development Workflow

Start Watch Mode

npm run gulp scripts-watch

This watches TypeScript files and rebuilds on changes.

Make Changes

Edit files in the ts/ directory:

// ts/Core/Chart/Chart.ts
export class Chart {
  // Your modifications
}

Test Changes

The build system automatically compiles to code/es-modules/:

npm test

CI/CD Integration

# .github/workflows/build.yml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm run build
      - run: npm test

Custom builds may not receive automatic updates. When upgrading Highcharts, rebuild your custom bundle to get the latest features and fixes.

Performance Tips

Use specific imports - Avoid importing the entire library
Enable minification - Always minify production builds
Enable gzip/brotli - Configure your server for compression
Use CDN for common builds - Let browsers cache standard builds
Lazy load modules - Load optional features on demand

Troubleshooting

Build Fails with TypeScript Errors

# Clean build cache
npm run gulp clean

# Rebuild
npm run build

Module Not Found

Ensure the module path is correct:

// Correct
import 'highcharts/es-modules/masters/modules/exporting.src.js';

// Incorrect
import 'highcharts/modules/exporting';

Large Bundle Size

Analyze your bundle:

npm install -D webpack-bundle-analyzer

// webpack.config.js
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin()
  ]
};

Getting Started

Core Concepts

Chart Types

Features

Advanced

Products

Creating Custom Builds

Build System Overview

Understanding the Module System

Build Commands

Creating a Custom Build

Build Configuration

TypeScript Configuration

Compilation Process

Using Highcharts Assembler

Tree Shaking with Modern Bundlers

Optimizing Build Size

Build Products

Custom Build Examples

Minimal Chart Build

Stock Chart with Indicators

Chart with Exporting

Development Workflow

CI/CD Integration

Performance Tips

Troubleshooting

Build Fails with TypeScript Errors

Module Not Found

Large Bundle Size

​Build System Overview

​Understanding the Module System

​Build Commands

​Creating a Custom Build

​Build Configuration

​TypeScript Configuration

​Compilation Process

​Using Highcharts Assembler

​Tree Shaking with Modern Bundlers

​Optimizing Build Size

​Build Products

​Custom Build Examples

​Minimal Chart Build

​Stock Chart with Indicators

​Chart with Exporting

​Development Workflow

​CI/CD Integration

​Performance Tips

​Troubleshooting

​Build Fails with TypeScript Errors

​Module Not Found

​Large Bundle Size

Build System Overview

Understanding the Module System

Build Commands

Creating a Custom Build

Build Configuration

TypeScript Configuration

Compilation Process

Using Highcharts Assembler

Tree Shaking with Modern Bundlers

Optimizing Build Size

Build Products

Custom Build Examples

Minimal Chart Build

Stock Chart with Indicators

Chart with Exporting

Development Workflow

CI/CD Integration

Performance Tips

Troubleshooting

Build Fails with TypeScript Errors

Module Not Found

Large Bundle Size