feat(bundlers): warn if plugins are not used

Author: Danielku15

packages/alphatab/src/Environment.ts

@@ -697,6 +697,15 @@ export class Environment {
         try {
             // @ts-expect-error
             if (typeof __webpack_require__ === 'function') {
+                // check if webpack plugin was used
+                // @ts-expect-error
+                if (typeof __ALPHATAB_WEBPACK__ !== 'boolean') {
+                    Logger.warning(
+                        'WebPack',
+                        `Detected bundling with WebPack but @coderline/alphatab-webpcak was not used! To ensure alphaTab works as expected use our bundler plugins. Learn more at https://www.alphatab.net/docs/getting-started/installation-webpack`
+                    );
+                }
+
                 return true;
             }
         } catch {
@@ -712,6 +721,15 @@ export class Environment {
         try {
             // @ts-expect-error
             if (typeof __BASE__ === 'string') {
+                // check if vite plugin was used
+                // @ts-expect-error
+                if (typeof __ALPHATAB_VITE__ !== 'boolean') {
+                    Logger.warning(
+                        'Vite',
+                        `Detected bundling with Vite but @coderline/alphatab-vite was not used! To ensure alphaTab works as expected use our bundler plugins. Learn more at https://www.alphatab.net/docs/getting-started/installation-vite`
+                    );
+                }
+
                 return true;
             }
         } catch {

packages/vite/src/alphaTabVitePlugin.ts

@@ -1,3 +1,4 @@
+import { detectionGlobalPlugin } from '@coderline/alphatab-vite/detectionGlobalPlugin';
 import type { AlphaTabVitePluginOptions } from './AlphaTabVitePluginOptions';
 import type { Plugin } from './bridge';
 import { copyAssetsPlugin } from './copyAssetsPlugin';
@@ -12,6 +13,7 @@ export function alphaTab(options?: AlphaTabVitePluginOptions) {
 
     options ??= {};
 
+    plugins.push(detectionGlobalPlugin());
     plugins.push(importMetaUrlPlugin(options));
     plugins.push(workerPlugin(options));
     plugins.push(copyAssetsPlugin(options));

packages/vite/src/detectionGlobalPlugin.ts

@@ -0,0 +1,38 @@
+import MagicString from 'magic-string';
+import type { Plugin, ResolvedConfig } from './bridge';
+
+const marker = '__ALPHATAB_VITE__';
+
+/**
+ * @public
+ */
+export function detectionGlobalPlugin(): Plugin {
+    let resolvedConfig: ResolvedConfig;
+    return {
+        name: 'vite-plugin-alphatab-global',
+
+        configResolved(config) {
+            resolvedConfig = config as ResolvedConfig;
+        },
+
+        shouldTransformCachedModule({ code }) {
+            return code.includes(marker);
+        },
+
+        async transform(code, id) {
+            if (!code.includes(marker)) {
+                return;
+            }
+
+            const s = new MagicString(code);
+            s.replaceAll(marker, JSON.stringify(true));
+            return {
+                code: s.toString(),
+                map:
+                    resolvedConfig.command === 'build' && resolvedConfig.build.sourcemap
+                        ? s.generateMap({ hires: 'boundary', source: id })
+                        : null
+            };
+        }
+    };
+}

packages/vite/test/Vite.test.ts

@@ -62,6 +62,8 @@ describe('Vite', () => {
                     expect(text).to.include('assets/alphaTab.worklet-');
                     // without custom chunking the app will bundle alphatab directly
                     expect(text).to.include(".at-surface");
+                    // ensure __ALPHATAB_VITE__ got replaced
+                    expect(text).to.not.include("__ALPHATAB_VITE__");
                     appValidated = true;
                 } else if (file.name.startsWith('alphaTab.worker-')) {
                     expect(text).to.include('initializeWorker()');

packages/webpack/package.json

@@ -42,7 +42,7 @@
         "test": "mocha"
     },
     "dependencies": {
-        "webpack": "^5.101.3"
+        "webpack": "^5.103.0"
     },
     "engines": {
         "node": ">=20.19.0"

packages/webpack/src/AlphaTabWebPackPlugin.ts

@@ -14,6 +14,7 @@ import type { webPackWithAlphaTab, webpackTypes } from './Utils';
 import { injectWebWorkerDependency } from './AlphaTabWebWorkerDependency';
 import { injectWorkletRuntimeModule } from './AlphaTabWorkletStartRuntimeModule';
 import { injectWorkletDependency } from './AlphaTabWorkletDependency';
+import { configureDetectionGlobal } from '@coderline/alphatab-webpack/DetectionGlobal';
 
 const WINDOWS_ABS_PATH_REGEXP = /^[a-zA-Z]:[\\/]/;
 const WINDOWS_PATH_SEPARATOR_REGEXP = /\\/g;
@@ -219,6 +220,7 @@ export class AlphaTabWebPackPlugin {
                 cachedContextify
             );
             this._configureAssetCopy(this._webPackWithAlphaTab, pluginName, compiler, compilation);
+            configureDetectionGlobal(pluginName, normalModuleFactory);
         });
     }
 

packages/webpack/src/AlphaTabWebWorkerDependency.ts

@@ -81,8 +81,8 @@ export function injectWebWorkerDependency(webPackWithAlphaTab: webPackWithAlphaT
             runtimeRequirements.add(webPackWithAlphaTab.webpack.RuntimeGlobals.getChunkScriptFilename);
 
             source.replace(
-                dep.range[0],
-                dep.range[1] - 1,
+                dep.range![0],
+                dep.range![1] - 1,
                 `/* worker import */ ${workerImportBaseUrl} + ${
                     webPackWithAlphaTab.webpack.RuntimeGlobals.getChunkScriptFilename
                 }(${JSON.stringify(chunk.id)}), ${webPackWithAlphaTab.webpack.RuntimeGlobals.baseURI}`

packages/webpack/src/AlphaTabWorkletDependency.ts

@@ -99,8 +99,8 @@ export function injectWorkletDependency(webPackWithAlphaTab: webPackWithAlphaTab
             runtimeRequirements.add(webPackWithAlphaTab.alphaTab.RuntimeGlobalWorkletGetStartupChunks);
 
             source.replace(
-                dep.range[0],
-                dep.range[1] - 1,
+                dep.range![0],
+                dep.range![1] - 1,
                 webPackWithAlphaTab.webpack.Template.asString([
                     '(/* worklet bootstrap */ async function(__webpack_worklet__) {',
                     webPackWithAlphaTab.webpack.Template.indent([

packages/webpack/src/DetectionGlobal.ts

@@ -0,0 +1,17 @@
+import type { Expression } from 'estree';
+import { tapJavaScript } from './Utils';
+
+/**
+ * @internal
+ */
+export function configureDetectionGlobal(pluginName: string, normalModuleFactory: any) {
+    const parserPlugin = (parser: any) => {
+        parser.hooks.evaluateIdentifier.for('__ALPHATAB_WEBPACK__').tap(pluginName, (expr: Expression) => {
+            const res = parser.evaluate('true');
+            res.setRange(expr.range);
+            return res;
+        });
+    };
+
+    tapJavaScript(normalModuleFactory, pluginName, parserPlugin);
+}

packages/webpack/test/WebPack.test.ts

@@ -30,10 +30,7 @@ describe('WebPack', () => {
                             filename: '[name]-[contenthash:8].js',
                             path: path.resolve('./out')
                         },
-                        plugins: [
-                            new AlphaTabWebPackPlugin(),
-                            new HtmlWebpackPlugin()
-                        ],
+                        plugins: [new AlphaTabWebPackPlugin(), new HtmlWebpackPlugin()],
                         optimization: {
                             minimize: false,
                             splitChunks: {
@@ -105,7 +102,8 @@ describe('WebPack', () => {
                     expect(text).to.include('class AlphaTabApiBase');
                     // ensure the library mode is active as needed
                     expect(text).to.include('alphaTabApp = __webpack_exports__');
-
+                    // ensure __ALPHATAB_WEBPACK__ got replaced
+                    expect(text).to.not.include('__ALPHATAB_WEBPACK__');
                     appValidated = true;
                 } else if (file.name.endsWith('.js')) {
                     if (text.includes('class AlphaTabApiBase')) {