vba-blocks

A package manager and build tool for VBA.

Installation

Windows

In powershell, run the following:

iwr https://vba-blocks.com/install.ps1 | iex

Mac

In terminal, run the following:

curl -fsSL https://vba-blocks.com/install.sh | sh

For more recent versions of Office for Mac, you will need to trust access to the VBA project object model for vba-blocks 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

Usage

new

Create a new folder with a blank/generated vba-blocks 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 vba-blocks 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 (vba-block.toml)

[project] or [package]

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

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

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

[src]

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 v12.19.0 or later
3. Install node-gyp dependencies for Mac or Windows

Build

1. Run npm install
2. Run npm run build
3. Run npm run build:addins

Test

1. Run npm test
2. Run npm run test:e2e

Release

1. Run npm version
2. Run npm run release