VexTab

A TypeScript VexTab parser and renderer built on VexFlow. This repository continues the original VexTab implementation by Mohit Muthanna Cheppudira, with a modern Vite-based build, TypeScript declarations, and Vitest test suite.

The package is published as @mcqj/vextab and is currently in alpha.

What is VexTab?

VexTab is a language that allows you to easily create, edit, and share music notation and guitar tablature. Unlike ASCII tab, which is designed for readability, VexTab is designed for writeability.

See the tutorial for the VexTab language.

Quick Start

Install the package and its published VexFlow dependency:

npm install @mcqj/vextab @mcqj/vexflow

Import the API and its stylesheet from your application:

import { Artist, Vex, VexTab } from '@mcqj/vextab';
import '@mcqj/vextab/style.css';

Use Div to render VexTab markup inside a DOM element:

<div id="score" width="680" scale="1" editor="true"
  editor-width="680" editor-height="330">
  options space=20
  tabstave notation=true key=A time=4/4

  notes :q =|: (5/2.5/3.7/4) :8 7-5h6/3 ^3^ 5h6-7/5 ^3^ :q 7V/4 |
  notes :8 t12p7/4 s5s3/4 :8 3s:16:5-7/5 :h p5/4
  text :w, |#segno, ,|, :hd, , #tr

  options space=25
</div>

import { Div } from '@mcqj/vextab';

new Div('#score');

Available element attributes include:

• width, height: rendering dimensions in pixels. Defaults are 400 and 200.
• renderer: svg (default) or canvas.
• editor: true enables the live editor.
• scale: rendering scale. Default is 1.0.
• editor-width, editor-height: live editor dimensions in pixels.

The package exports Vex, Artist, VexTab, Div, and Player.

VexTab API

If you want to do more interesting things with VexTab, you can use the API directly.

import { Artist, Vex, VexTab } from '@mcqj/vextab';

const Renderer = Vex.Flow.Renderer;

// Create VexFlow Renderer from canvas element with id #boo
const renderer = new Renderer(document.querySelector('#boo')!, Renderer.Backends.SVG);

// Initialize VexTab artist and parser.
const artist = new Artist(10, 10, 600, { scale: 0.8 });
const tab = new VexTab(artist);

try {
  tab.parse('tabstave notation=true');
  artist.render(renderer);
} catch (e) {
  console.error(e);
}

See tests/playground.ts for a working example.

Developers

Requirements: Node.js (>= v24) and npm. The checked-in package configuration uses the published @mcqj/vexflow package, so no sibling VexFlow checkout is required.

npm install
npm run dev

The development server runs on http://localhost:9005. Open http://localhost:9005/tests/playground.html for interactive rendering checks.

Scripts

All available package.json scripts:

| Command | Description | | --- | --- | | npm run dev | Start the Vite development server on port 9005. | | npm run build | Build the ESM library, declaration files, stylesheet, and source maps into dist/. | | npm run preview | Serve the production library assets from dist/ on port 8052. This build has no demo page. | | npm test | Start Vitest in watch mode. | | npm run test:run | Run the Vitest suite once. | | npm run lint | Run ESLint across the repository. | | npm run clean | Remove dist/. | | npm run generate-parser | Regenerate the VexTab parser from src/vextab.peggy. | | npm run prepublishOnly | Run linting, tests, and the production build before publishing. |

Run the release gate locally with:

npm run prepublishOnly

For rendering or parser changes, also verify the result in the playground.

Using a local VexFlow checkout

To develop against a local VexFlow checkout, replace the published dependency with a file reference in package.json:

"@mcqj/vexflow": "file:../vexflow"

Then run npm install. Restore the published version before publishing VexTab.

Tooling and Dependencies

Runtime dependency:

• @mcqj/vexflow - Music engraving and rendering.

Development tooling:

• TypeScript - Type checking and declaration generation.
• Vite - Development server and library build.
• Vitest with jsdom and canvas - Test runner and browser-like test environment.
• ESLint with @typescript-eslint and eslint-plugin-import - Static analysis.
• Peggy - Parser generation from the VexTab grammar.
• vite-plugin-checker and vite-plugin-dts - Development type checking and declaration-file output.

Help

Questions? Ask on the VexFlow Google Group.

License

This project is distributed under the terms in LICENSE.