Vlocode: Vlocity/Salesforce support libraries

This is the monorepo root for all @vlocode packages and the Vlocode VSCode extension. For information on the Vlocode VSCode extension click here.

Packages

• @vlocode/util - re-unable utility functions and classes
• @vlocode/vlocity-deploy - high performance Vlocity DataPack deployment library
• @vlocode/core - IoC core and logging framework
• @vlocode/salesforce - Salesforce specific classes and functions
• Vlocode - Vlocode VSCode extension
• @vlocode/cli - Vlocode Standalone DataPack deployment CLI

Documentation

Guides for exporting and importing (deploying) Vlocity DataPacks live in the documentation folder:

• Overview - what datapacks are and how the docs fit together
• Concepts - source keys, matching keys, references and dependencies
• CLI reference - installing, authenticating and running the vlocode CLI
• Exporting datapacks - the vlocode export command and export pipeline
• Building export definitions - authoring the export-definition YAML
• Importing / deploying datapacks - the vlocode deploy command and deployment pipeline
• Customizing deployment with specs - extending export and import

API reference documentation is generated with TypeDoc and published at vlocode.curlybracket.nl.

Setup development environment

Vlocode uses pnpm as package manager and lerna release manager. To setup a developer environment for Vlocode you should always use the latest LTS version of node with corepack. VScode is the preferred IDE for developing and debugging.

• check out this repository
• enable corepack and activate the pnpm package manager

$ corepack enable
$ corepack prepare $(node -p "require('./package.json').packageManager") --activate

• install all dependencies using pnpm, this will install all dependencies for packages in the monorepo

pnpm install

• open the folder in VSCode and start coding; the launch.json and tasks.json that are part of this repository should allow you to run both the Vlocode CLI as well as debug the Vlocode extension without requiring any configuration

Tests

Each vlocode package comes with unit tests. To run all tests simply run pnpm test from the root folder which will run all package tests. P

Vlocode uses jest as test runner and is pre-configured to generate a test converge report.

Note you should run pnpm build if you are not running a watcher to ensure that all packages are transpiled and linked under node_modules.

Beta (Prerelease) Versions

You can cut and publish a beta (preview) version of all packages and the VSCode extension using the new release-beta script. Beta builds:

• use semantic version prerelease identifiers (e.g. 1.34.0-beta.0)
• are published to GitHub Releases marked as Pre-release
• are uploaded to the VSCode Marketplace as Preview (using vsce --pre-release)
• can be iterated (beta.1, beta.2, ...); when you later publish a stable version (e.g. 1.34.0) the preview flag is removed automatically by Marketplace

Creating a beta

pnpm release-beta

This runs lerna version prerelease --preid beta which:

1. Determines the next prerelease version for each changed package (conventional commits)
2. Updates lerna.json + individual package.json versions (e.g. 1.34.0-beta.0)
3. Commits the changes and creates a git tag v1.34.0-beta.0

Push the tag to trigger the GitHub Actions Release workflow:

git push origin HEAD --follow-tags

Publishing flow (CI)

The GitHub Actions release workflow detects prerelease versions (hyphen in the version) and automatically:

• passes --pre-release to the extension packaging & publish steps
• marks the GitHub Release as pre-release when the version contains a hyphen
• publishes all @vlocode/* npm packages with the beta dist-tag (so they don't overwrite latest)

Consuming beta npm packages

Install a beta version by either specifying the full version or using the beta tag:

pnpm add @vlocode/core@beta
pnpm add @vlocode/util@1.34.0-beta.0   # explicit version example

To upgrade back to the stable channel later:

pnpm up @vlocode/core@latest @vlocode/util@latest

Manually publishing the extension beta (optional)

If you need to publish locally (e.g. testing credentials):

pnpm publish-extension-beta

This builds the extension and runs vsce publish --pre-release in the extension package.

Converting beta to stable

When ready for GA:

pnpm release-minor   # or release-patch / manual lerna version command
git push origin HEAD --follow-tags

GitHub Actions will package without the prerelease flag and publish a normal release.