Skip to main content

Installation (Vite)

since 1.3.0
info

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

import { defineConfig } from "vite";
import { alphaTab } from "@coderline/alphatab/vite";

export default defineConfig({
plugins: [alphaTab()]
});

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 Vite, 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:

Vite 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 Vite plugin which takes care of configuring Vite 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 Vite settings can be customized. Typically you will find a vite.config.<ext> in your project. You might check out a fresh project created via https://vitejs.dev/guide/#scaffolding-your-first-vite-project

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

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

// Add the plugin to your config
export default defineConfig({
plugins: [alphaTab()]
});

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:

export default defineConfig({
plugins: [alphaTab({
alphaTabSourceDir: path.resolve('../../node_modules/@coderline/alphaTab/dist')
})]
});

Samples

You can check out the sample projects at https://github.com/CoderLine/alphaTabSamplesWeb/tree/main/src to find a reference you can look at. They offer some very minimal setup of alphaTab for different project constellations.

warning

Angular does not provide built-in ways of customizing bundler configurations. In the latest Versions they use Vite for the development server and ESBuild for building. But they offer no customizations to this.

The popular alternative builders https://github.com/just-jeb/angular-builders also do not have support for Vite yet. This means if you want to use AlphaTab with your Angular application you have to use WebPack as bundler.