Skip to main content

Installation (WebPack)

since 1.3.0
info

TL;DR: AlphaTab comes with a WebPack 5 plugin which should be added to your WebPack config to guarantee compatibility.

import { AlphaTabWebPackPlugin } from '@coderline/alphatab/webpack';

const webpackConfig = {
plugins: [
new AlphaTabWebPackPlugin()
]
}

alphaTab internally off-loads some work to background workers to not block the browser while rendering or generating audio. These background workers are realized through Web Workers and Audio Worklets.

Without bundlers like WebPack, alphaTab simply launches these workers by starting the ./alphaTab.worker.[m]js or ./alphaTab.worklet.[m]js. The dependency diagram without bundlers using JavaScript modules looks like this:

WebPack might splitup and merge files which makes it impossible for alphaTab to locate the right entry points for the Workers.

Due to this reason alphaTab ships a custom WebPack plugin which takes care of configuring WebPack automatically and ensuring that all features work as intended:

  • It ensures the Web Font (Bravura) and the SoundFont (SONiVOX) shipped with alphaTab are copied to the build output and made available through <root>/font/ and <root>/soundfont/ of your application.
  • It ensures Web Workers and Audio Worklets are correctly configured and working.

If you are using a framework like Angular, React or Vue.js you might read in their documentation on how the WebPack settings can be customized.

info

We are also using this plugin on alphaTab.net ourselves.

Unless there is something special to your project setup, adding the plugin to the list is everything you need to do:

// CommonJS
const AlphaTabWebPackPlugin = require('@coderline/alphatab/webpack');
// JavaScript modules
import { AlphaTabWebPackPlugin } from '@coderline/alphatab/webpack';

// Add the plugin to your config
const config = {
plugins: [
new AlphaTabWebPackPlugin()
]
};

Configure Plugin

The plugin behavior can be configured and customized depending on needs.

By default the alphaTab files are searched within node_modules/@coderline/alphaTab/dist. If you're using a special alphaTab build or your project structure is special, you can tell the plugin through a setting where to find the files:

new AlphaTabWebPackPlugin({
alphaTabSourceDir: path.resolve('../../node_modules/@coderline/alphaTab/dist')
})

Angular

Unfortunately Angular does not provide an out-of-the-box way to customize the used WebPack config and therefore it can be a bit tricky to get the alphaTab plugin into place. The @angular-builders/custom-webpack enables adding custom webpack configs.

In our Angular sample was created like this:

  1. Create a new angular app via
    • ng new alphatab-app
  2. Install the package to enable custom webpack configs:
    • npm i -D @angular-builders/custom-webpack
  3. Modify the angular.json to enable the custom webpack config:
{
"projects": {
"alphatab-app": {
"projectType": "application",
"schematics": {},
"root": "",
"sourceRoot": "src",
"prefix": "app",
"architect": {
"build": {
- "builder": "@angular-devkit/build-angular:application",
+ "builder": "@angular-builders/custom-webpack:browser",
+ "options": {
+ "customWebPackConfig": {
+ "path": "./custom-webpack.config.js"
+ }
...
"serve": {
- "builder": "@angular-devkit/build-angular:dev-server",
+ "builder": "@angular-builders/custom-webpack:dev-server",
+ "options": {
+ "buildTarget": "alphatab-app:build"
+ },
  1. Add a custom-webpack.config.js and add the alphaTab Plugin
const { AlphaTabWebPackPlugin } = require('@coderline/alphatab/webpack');

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