vbapm

A package manager and build tool for VBA.

Installation

Option 1: Install as a global npm package

Prerequisites: Node.js v22 or higher.

npm install -g vbapm

Option 2: Standalone installer

Installation instructions

Windows

In powershell, run the following:

iwr https://raw.githubusercontent.com/vbapm/installer/refs/heads/main/install.ps1 | iex

Mac

In terminal, run the following:

curl -fsSL https://raw.githubusercontent.com/vbapm/installer/refs/heads/main/install.sh | sh

For more recent versions of Office for Mac, you will need to trust access to the VBA project object model for vbapm to work correctly:

Trust access to the VBA project object model

1. Open Excel
2. Click "Excel" in the menu bar
3. Select "Preferences" in the menu
4. Click "Security" in the Preferences dialog
5. Check "Trust access to the VBA project object model" in the Security dialog

---

If you run into any issues during installation, please see the known issues for the installer or create a new issue with details about what's happening.

🚀 You're ready to go! Open a new command-line session (cmd / terminal) and try vba --help

Programmatic Usage

You can also use vbapm as a library (e.g. from a VS Code extension):

const { buildProject, loadProject, env } = require("vbapm");

// Override working directory
env.cwd = "/path/to/project";

const project = await loadProject();
await buildProject(project);

Usage

new

Create a new folder with a blank/generated vbapm project inside

Create a folder "project-name" with a blank xlsm project:

vba new project-name.xlsm

(equivalent to above)

vba new project-name --target xlsm

Create a folder "from-existing" with a project from an existing workbook:

vba new from-existing --from existing.xlsm

Create a blank package for sharing as a library between projects:

vba new json-converter --package

init

Create a blank/generated vbapm project in the current folder

Create a blank xlsm project with the current folder's name:

vba init --target xlsm

Create a project from an existing workbook:

vba init --from existing.xlsm

Create a blank package:

vba init --package

build

Build an Excel workbook from the project's source. The built file is located in the build/ folder and if a previously built file is found it is moved to /.backup to protect against losing any previously saved work.

Build a project:

vba build

Build and open a project for editing:

vba build --open

Build a package using a blank target:

vba build --target xlsm

Build a project, excluding any development src, dependencies, or references:

vba build --release

export

Once you've completed your edits and are ready to commit your changes, export your project with vba export.

Export a project:

vba export

Export a previously-built package:

vba export --target xlsm

run

vba run is a useful utility function for running a public macro in the given workbook, passing up to 10 arguments, and if it returns a string value, outputing it to the console.

' (Module: Messages.bas)
Public Function SayHi(Name As Variant) As String
  SayHi = "Howdy " & Name & "!"
End Function

vba run Messages.SayHi Tim
Howdy Tim!

Manifest (vbaproject.toml)

The vbapm manifest (vbaproject.toml) serves as the foundation for your project and provides information on your package, source, dependencies, references, and targets, as detailed below.

[project] or [package]

The [package] / [project] section includes general information about your package. You should choose [package] if your project is only intended to be used as a utility inside another project and [project] if your project is a standalone tool.

Here are the main properties:

• name (required)
• version (required for [package])
• authors (required for [package])
• target (required for [project])

Example 1

[project]
name = "awesome-excel-project"
target = "xlsm"

Example 2

[package]
name = "awesome-vba-package"
authors = ["Me <me@email.com>"]
version = "0.1.0"

[version]

vbapm follows Semantic Versioning. Make sure you adopt a compatible versioning approach if you intend to publish to the repository.

[target]

target is used to define what application/extension to use when building your project. It can be a string for the extension, in which case target/ includes the source files for creating the target. Otherwise, type and path can be used to define a custom target path.

Example 1:

target = "xlsm"
# equivalent to target = { type = "xlsm", path = "target" }

Example 2:

target = { type = "xlam", path = "targets/xlam" }

[src]

Will contain the list of source code files to be included in the VBA-Enabled Document at build time.

name = "path" or

• path

[src]
A = "src/A.bas"
B = "src/B.cls"
C = { path = "src/C.bas" }

[dependencies]

name = "version" or

• version
• path
• git (and branch, tag, or rev)

[dependencies]
a = "1" # Equivalent to ^1
b = "=2.0.0" # Precisely 2.0.0
c = { version = "3" }

d = { path = "./packages/d" }

e = { git = "https://..." } # master
f = { git = "https://...", branch = "dev" }
g = { git = "https://", tag = "bugfix" }
h = { git = "https://", rev = "abc1234" }

[references]

• version ("MAJOR.MINOR")
• guid ("{...}")

[references]
Scripting = { version = "1.0", guid = "{...}" }

[dev-src,dependencies,references]

[dev-src], [dev-dependencies], and [dev-references] are included during development and are excluded when building with the --release flag (i.e. vba build --release)

Development

Prerequisites

1. git clone this repo
2. Install Node.js v22 or later
   • Note: For CLI builds, Node v23+ only supports Windows x64 (win-x64). 32-bit Windows (win-x86) is no longer available upstream.
3. Install node-gyp dependencies for Mac or Windows

Build

1. Run npm install
2. Run npm run format
3. Run npm run build
   It will build the CLI/library in lib, plus ensured vendor node runtime is available.
4. Run npm run build:addins
   It will build the Excel addin that performs workbook/VBA operations from inside Office.

Test

1. Run npm test
   It will run unit tests
2. Run npm run test:e2e
   It will run the end-to-end CLI scenarios in excel.e2e.ts, covering workflows like build, export, new, and version against fixtures.
   To keep temporary e2e work folders for manual inspection, set KEEP_E2E_TMP=1 before running (PowerShell: $env:KEEP_E2E_TMP=1; npm run test:e2e, cmd: set KEEP_E2E_TMP=1 && npm run test:e2e).

Install local version

To install the local version you can use the devinstall.ps1 script available in the installer submodule.

# Update submodule
git submodule update --init --recursive installer

# Run devinstall
.\installer\devinstall.ps1

Release

1. Run npm version
2. Run npm run release

Acknowledgments

This project is a fork of the original vba-blocks project by Tim Hall.