Use with Node.js

[kyledecot]

Is it possible to use alphaTab with Node JS (for SSR–similar to #194)? Recently I tried doing the following in a Next.js application:

import { AlphaTabApiBase } from "@coderline/alphatab";

This however gives the following error:

ReferenceError: document is not defined

It appears that this is caused by Environment.scriptFile.

[Danielku15]

Hi.
Currently the JavaScript version of alphaTab is only designed for browser usage, not for server usage. Most low level APIs should work as alphaTab does not directly depend on the browser for many operations. Unfortunately there exists a bit of code in the JS flavor which tries to setup browser specific things and this fails.

The usual AlphaTabApi or AlphaTabApiBase objects which is documented overall the website, is meant for usage together with a UI (e.g. the browser DOM).

I added #542 to the backlog but I'm also happy to accept PRs.

As a workaround you could try to patch some globals to satisfy the needs of alphaTab. I would need to do some tests but something like the following code might make it work:

// set some globals to satisfy alphaTab
global.window = {
	devicePixelRatio: 1
};
global.document {
	window: global.window
	currentScript: {
		src: 'alphaTab.js'
	}
};
import * as alphaTab from "@coderline/alphatab";
const settings = new alphaTab.Settings();
let score: Score = alphaTab.importer.ScoreLoader.loadScoreFromBytes(data, settings);

[WindBise]

I add globals as below:
global.window = {
devicePixelRatio: 1
};
global.document = {
window: global.window,
currentScript: {
src: 'alphaTab.js'
}
};
but there's still one error:
Uncaught ReferenceError: window is not defined
at index.js?ts=1613179798472:1
at ed3525c4-7168-4749-b87a-29415ca8d90f:1
it seems that webpack try to do something with window object but window is not defined before global object is declared:

_N_E =
(window["webpackJsonp_N_E"] = window["webpackJsonp_N_E"] || []).push([["pages/index"],{

/***/ "./global.js":
/*!*******************!*\
  !*** ./global.js ***!
  \*******************/
/*! no static exports found */

[Danielku15]

AlphaTab should not be bundled with other files unless it can be guaranteed the other files do not access the DOM. AlphaTab launches a Web worker for rendering where the window object will not be available. This is nothing node.js specific but a general topic also valid for Browsers. See https://alphatab.net/docs/getting-started/installation-web#bundling

I guess next.js in your case has sort of a "window" object available due to the fact it provides server side rendering. You could try setting useWorkers to false for your usecase. Otherwise you will need to use the Low Level APIs directly which by default do not spawn Workers.

[WindBise]

It occured when i try to use alphatab in next.js app. Have you solved this problem? Maybe you can also give me some hints to walk around this.

[Danielku15]

You should be able to get started with https://alphatab.net/docs/guides/nodejs
I just merged #544 and the version with related fixes should be available soon.

I also added a follow up #545 to provide raster graphics rendering in node environments. Until now only the SVG rendering part is available out-of-the-box.

I guess there might be still some "usability" topics which could be improved to integrate alphaTab easier into some workflows. But for this I will need some more concrete use cases. Until now the usage is quite low-level and will require quite some skills to integrate it well into backend rendering workflows.

[kyledecot]

Thanks for all of your quick work on this!