Creating Custom Builds

Learn how to create optimized custom builds of Highcharts tailored to your specific needs

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

npm

# 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

Creating a Custom Build

1. 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'
   ];
   
2. 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;
   
3. Bundle with Your Tool

   Use your preferred bundler:

   webpack

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

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

1. Use ES Modules

   Always prefer ES modules for better tree shaking:

   import Highcharts from 'highcharts/es-modules/masters/highcharts.src.js';
   
2. 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';
   
3. 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:

Highcharts

npm run gulp scripts

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

1. Start Watch Mode

   npm run gulp scripts-watch
   

   This watches TypeScript files and rebuilds on changes.

2. Make Changes

   Edit files in the ts/ directory:

   // ts/Core/Chart/Chart.ts
   export class Chart {
     // Your modifications
   }
   
3. 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

1. Use specific imports - Avoid importing the entire library
2. Enable minification - Always minify production builds
3. Enable gzip/brotli - Configure your server for compression
4. Use CDN for common builds - Let browsers cache standard builds
5. 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()
  ]
};