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:

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 <[email protected]>"]
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