Contributing

alphaTab welcomes contributions of every kind — bug reports, feature requests, code, and documentation. Everything happens on GitHub. All participation follows the project's code of conduct.

Report a bug

Open an issue in the alphaTab repository using the bug-report template. Open an issue only when:

• You can reproduce the problem and describe the exact steps to reproduce it.
• Something is clearly missing from an existing, documented feature.

Fill every field in the template — reproduction, environment, expected versus actual behaviour. Issues that skip the template are closed unread. Two minutes of context on your side saves multiple back-and-forth rounds on the maintainer side.

Before opening a new issue, search the tracker — if the topic already exists, comment on the existing thread instead of creating a duplicate.

Ask a question or float an idea

Anything short of a confirmed bug belongs in GitHub Discussions, not the issue tracker. Use Discussions when:

• You have an idea for a feature and want to talk it through before it becomes work.
• You need help using alphaTab.
• You are not sure whether alphaTab already supports what you need.
• Something looks wrong but you are not yet certain whether the cause sits in alphaTab or in your integration.

Discussions keep the issue tracker focused on confirmed work items.

Contribute code

alphaTab lives in one monorepo — github.com/CoderLine/alphaTab — built on npm workspaces. Every package listed below is a workspace under packages/; the documentation site is the website/ workspace:

• alphatab — the main library and the source of truth for all platforms
• alphatex — the alphaTex text-format parser and tools
• csharp — the .NET build, transpiled from the TypeScript source
• kotlin — the Kotlin/Android build, transpiled from the TypeScript source
• transpiler — the TypeScript-to-C#-and-Kotlin transpiler both platforms consume
• vite, webpack — the bundler plugins
• monaco, lsp — the Monaco editor integration and alphaTex language server
• playground — the local dev sandbox
• tooling — shared build configuration used by the other packages

Branching model

alphaTab uses a GitFlow-style layout:

• develop — the default branch and integration point. All new work targets develop.
• feature/<name> — one branch per new feature or bug fix, taken off develop. Name it after the feature (feature/alphatex-alternate-endings) or the issue (feature/issue-1234).
• main — the last released, tagged state.
• release/* — short-lived branches for stabilising a release.
• hotfix/* — patches against a shipped release.

Pull request workflow

1. Fork alphaTab to your GitHub account.
2. Branch off develop with a feature/<name> branch.
3. Make your change. Include tests where reasonable, and run the relevant test scripts locally (see Development environment).
4. Open a pull request against develop. Fill out the PR template — what changed and why. Mark it as a draft pull request if it is not yet ready for review.
5. Clear the draft state once you are ready. CI runs against every push.
6. Address review feedback. Style, structure, or scope adjustments may come back — this is normal.
7. Once approved and green, a maintainer merges the change into develop. Contributors are credited in the release notes when the change ships.

License and contributor ownership

alphaTab is released under MPL-2.0. By contributing you transfer ownership of your change to the alphaTab project. This is not about taking your work away — it keeps the door open to future license changes (for example to MIT) without needing to track down every past contributor. Any such change will be discussed publicly before it happens. Keeping alphaTab a free and open library for anyone to integrate is a primary goal.

Development environment

You will need:

• Node.js 20 or newer — for TypeScript builds, tests, and workspace management
• .NET SDK 8.0 or newer — only if you plan to build or test the C# port
• Java 17+ and the Android SDK — only if you plan to build or test the Kotlin/Android port

Any modern web-focused IDE works. Visual Studio Code is a good default — the repository ships editor settings and recommended extensions it picks up automatically.

Clone the repository and install dependencies once:

git clone https://github.com/CoderLine/alphaTab.git
cd alphaTab
npm install

npm install installs every workspace, including the documentation site under website/, in one pass. From here on, run scripts against the root — the root package.json orchestrates the workspaces.

Everyday commands

Run at the repository root:

npm run dev         # start the local playground with the current alphaTab source
npm run build       # build the alphatab package
npm test            # run the alphatab test suite (vitest)
npm run lint        # lint every workspace via Biome
npm run typecheck   # run tsc --noEmit across every workspace
npm run clean       # remove build output from every workspace

Platform-specific commands

The web build is the default. To build or test the other platforms, use the per-platform scripts.

Web (main library + bundler plugins)

npm run build-web   # build alphatab + webpack + vite plugins
npm run test-web    # run every web-workspace test suite

C# / .NET

npm run build-csharp   # transpile TypeScript to C#, then run dotnet build
npm run test-csharp    # run the .NET unit tests via dotnet test

Kotlin for Android

npm run build-kotlin   # transpile TypeScript to Kotlin, then run gradle assembleRelease
npm run test-kotlin    # run the Android instrumentation tests

Bundler plugins in isolation

npm run build-vite     # build only the Vite plugin
npm run test-vite      # test only the Vite plugin
npm run build-webpack  # build only the WebPack plugin
npm run test-webpack   # test only the WebPack plugin

Toolchain

TypeScript is the source of truth. All alphaTab development happens in the packages/alphatab workspace. The packages/transpiler workspace is a custom compiler built on top of the TypeScript compiler that translates the same source to C# and Kotlin. The csharp and kotlin packages consume the transpiler and hand off to dotnet build and gradle respectively.

alphaTab targets zero runtime dependencies. The core modules are written to run on any platform with a garbage collector — JavaScript, .NET, or Kotlin for Android — without pulling in third-party libraries. Contributions to the core need to keep this constraint in mind: no new runtime dependencies without an architectural discussion first.

Code style

Biome (biomejs.dev) formats and lints the TypeScript source. Run npm run lint before opening a pull request — CI will run it too. The formatter uses four-space indentation and a 120-character line width; the configuration lives in biome.jsonc at the repository root. The documentation site under website/ is linted but not formatted by Biome; it keeps its own code style.

Contribute to the documentation

The documentation site lives in the website/ folder of the alphaTab repository and is built with Docusaurus. Documentation changes go into the same pull request as the code they describe.

Every documentation page follows the documentation style guide — voice, structure, formatting, and code-sample rules. Read it before writing new pages or rewriting existing ones.

The API, settings and type reference pages are generated from alphaTab's JSDoc when the site builds. To change them, edit the JSDoc in packages/alphatab/src or the hand-written _<member>.mdx partials next to the generated pages.

The site builds against the local alphaTab packages. Build them once, and again after changing their source, then start the site from the repository root:

npm run build-web
npm run build-language-server
npm run build-monaco
npm run dev-website

The dev server serves the site at http://localhost:3000 with hot-reload. npm run build-website runs the production build, including the broken-link check. Open a pull request against develop when your change is ready.