Skip to content

Developer Setup Guide

Jump to bottom
Matheus Gonçalves edited this page Aug 14, 2025 · 2 revisions

Developer Setup Guide

Welcome to the Salesforce Metadata Opener developer onboarding guide. This document helps you set up your local environment to develop, run, test, and package the VS Code extension.

Requirements

Install the following first:

  • VS Code >= 1.102.0
  • Node.js >= 20.x and npm >= 9.x
  • Git
  • Salesforce CLI (sf) on your PATH
  • VSCE (@vscode/vsce) if you want to package .vsix files locally
  • Recommended VS Code extension: ESLint

Install prerequisites

Node via nvm, macOS or Linux

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# restart your shell, then:
nvm install 20
nvm use 20
node -v
npm -v

Windows users can use nvm-windows or install Node from nodejs.org.

Salesforce CLI

Install the sf CLI for your OS. After installation:

sf --version

Clone and install

git clone https://github.com/gitmatheus/sf-metadata-opener.git
cd sf-metadata-opener
npm ci

npm ci gives deterministic installs that match the lockfile.

Run the extension in VS Code

Launch a VS Code Extension Development Host.

Normal dev run

npm run local

Dev run with all other extensions disabled

npm run local-no-ext

Build and watch

This project uses esbuild and prepares the manifest before compiling.

Compile once

npm run compile

Watch for changes

npm run watch

This runs watch:esbuild and watch:tsc in parallel.

Test and lint

npm test
npm run lint

npm test triggers pretest, which compiles tests, compiles the extension, and lints the code.

Package

Create a production bundle:

npm run package

Create a .vsix for local installation:

vsce package --no-dependencies

npm run publish also calls vsce package --no-dependencies.

Key npm scripts

From package.json:

Script What it does
prepare:manifest Builds the extension manifest files before compile
check-types Type checks with tsc --noEmit
compile Runs manifest prep, type check, then node esbuild.js
watch Runs watch:* scripts in parallel
watch:esbuild node esbuild.js --watch
watch:tsc tsc --noEmit --watch
package Production build via node esbuild.js --production
vscode:prepublish Calls npm run package
publish vsce package --no-dependencies
compile-tests Compiles tests to out with tsc
watch-tests Watches tests to out
pretest Runs compile-tests, compile, and lint
lint ESLint on src with .ts files
test Runs tests via vscode-test
local-no-ext Compile, then launch VS Code with other extensions disabled
local Compile, then launch VS Code with this folder as the dev extension

Project structure

  • src/ TypeScript sources
  • scripts/manifest/ manifest generation scripts
  • esbuild.js build configuration
  • dist/ output folder for bundled extension
  • package.json scripts and dependencies
  • tsconfig.json TypeScript configuration
  • webpack.config.js present for historical reasons, current builds use esbuild

Using a Salesforce org during development

Authenticate a default org for testing.

sf org login web -s -a mySandbox
sf org list

The extension resolves metadata with sf data query in many flows, so make sure your default org is set correctly.

Extension settings for developers

Open VS Code Settings and search for Salesforce Metadata Opener, or set them in settings.json.

{
  "SalesforceMetadataOpener.useSfCommandToOpenMetadata": true,
  "SalesforceMetadataOpener.deployBeforeOpen": true
}
  • useSfCommandToOpenMetadata controls whether the extension may use sf org open --source-file for supported types, or always build direct URLs
  • deployBeforeOpen controls whether to deploy the local file before opening

Typical workflow

  1. npm ci
  2. npm run watch in one terminal
  3. npm run local in another terminal
  4. Open a Salesforce project folder with metadata files
  5. Use the context menu or Command Palette to trigger commands

Troubleshooting

  • sf not found. Install the Salesforce CLI and add it to your PATH
  • Engine mismatch. Update VS Code to 1.102.0 or newer
  • Type errors. Ensure Node 18 is active, then npm ci again
  • No context menu items. Confirm the file name matches a supported pattern, for example .flow-meta.xml, .bot-meta.xml, .dashboard-meta.xml, .report-meta.xml
  • Dev host does not reload. Keep npm run watch running, or run npm run compile
  • Packaging errors. Install @vscode/vsce globally before running vsce package

Ready to contribute

Create a branch, run npm run watch and npm run local, and iterate. Open a pull request when ready. Happy building.

Clone this wiki locally