Skip to content

Contributing

Any type of contribution is welcome.

It does not have to be a new plugin,

anything like reporting bugs, improving the docs, submitting an idea for a new feature or plugin is appreciated.

You can also sponsor the development to give back to the community, just like other companies did already.

Sponsors are listed in the README.

Getting Started

  1. Fork this repository and clone your fork

  2. Install dependencies

[!NOTE] Make sure to run these commands in your sfdx-browserforce-plugin directory.

npm ci
npx playwright install chromium

Scaffolding a new plugin

Let's say you want to develop a new plugin to enable/disable Administrators Can Log in as Any User. Please note that this is only an example. In fact this is supported in the Metadata API.

You can scaffold a new plugin by running:

npm run generate:plugin -- --name AdminsCanLogInAsAnyUser

Bravo 👏, you have just generated a working browserforce plugin!

Building

TypeScript code needs to be transpiled to JavaScript. To do this, run the following command:

npm run build

Want to see it in action?

Let's create a Scratch Org

npm run develop

and now we can run it:

BROWSERFORCE_HEADLESS=false ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/enable.json
BROWSERFORCE_HEADLESS=false ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/disable.json

[!TIP] Instead of manually running these commands while developing, we will run the E2E tests instead:

npm run test:e2e -- -g "AdminsCanLogInAsAnyUser"
  AdminsCanLogInAsAnyUser
    ✔ should enable
    ✔ should already be enabled
    ✔ should disable
    ✔ should already be disabled
  4 passing (6s)

Developing plugins

For the following, we assume that your scaffolded plugin lives in src/plugins/admins-can-log-in-as-any-user.

$ tree src/plugins/admins-can-log-in-as-any-user
src/plugins/admins-can-log-in-as-any-user
├── disable.json        <-- example config file for manual testing
├── enable.json         <-- example config file for manual testing
├── index.e2e-spec.ts   <-- end-to-end test
└── index.ts            <-- implementation, including the schema for configuration (zod)

We'll start with the configuration schema.

Configuration Schema

Browserforce leverages zod for its configuration. The schema lives directly in the plugin's index.ts, and the plugin's Config type is derived from it with z.infer<typeof adminsCanLogInAsAnyUserSchema>, so the type and the schema cannot drift.

Example: Given you have defined the property enabled in the schema for your plugin AdminsCanLogInAsAnyUser, end users can create a browserforce configuration file looking like this (entry point: settings -> adminsCanLogInAsAnyUser).

index.ts

import { z } from 'zod';

export const adminsCanLogInAsAnyUserSchema = z
  .object({
    enabled: z
      .boolean()
      .meta({
        title: 'Enable Administrators Can Log in as Any User',
        description: 'The description you want to be displayed as toolip when the user is editing the configuration',
      })
      .optional(),
  })
  .meta({
    id: 'adminsCanLogInAsAnyUser',
    title: 'Administrators Can Log in as Any User Settings',
    examples: [{ enabled: true }],
  });

config/setup-admin-login-as-any.json

{
  "$schema": "",
  "settings": {
    "adminsCanLogInAsAnyUser": {
      "enabled": true
    }
  }
}

The entry point (key) is automatically determined by the plugin name (starting lowercase). This allows to run multiple actions (from multiple plugins) using a single configuration file.

src/plugins/schema.json is generated from all plugin schemas by npm run generate:schema (also run by npm run build and by the plugin scaffolder), is committed, and must never be edited by hand; CI fails if the committed file differs from the generated one.

If your plugin has a secret configuration field (e.g. an API key or password), wrap it with the password() helper exported from src/plugins/utils.ts, e.g. consumerSecret: password(z.string()).optional(). Its value is then masked in browserforce apply output.

sf browserforce plugins list describes every plugin to tools that build Browserforce configurations (like sfdx-hardis deployment actions), from the JSON Schema of the plugin. Besides title and description, add these keys to .meta():

  • examples (on the plugin schema): at least one ready-to-use value of settings.<key>. Unit tests validate them against the schema. Unlike the JSON files of the plugin folder, they are shown to users, so keep test fixtures out of them.
  • 'x-irreversible': true (on a field): the value cannot be changed back once applied (e.g. a feature that cannot be disabled). Explain it in the field's description.
  • 'x-user-interface': 'classic' (on the plugin schema): the feature only exists in Salesforce Classic.
  • 'x-prerequisites' (on the plugin schema): what the org needs first (managed package, license, feature).

Documentation page

Each plugin gets a page on the documentation site, generated from its schema. Write its description in the .meta() of the plugin schema, in Markdown:

  • the Setup menu path and the URL of the page, e.g. Setup: **Email → Deliverability** (`/lightning/setup/OrgEmailSettings/home`);
  • what the setting does, and why the Metadata API cannot do it;
  • its screenshot, referenced by its path from the repository root: ![Deliverability](src/plugins/email-deliverability/screenshot.webp). The documentation site shows a copy made by npm run generate:docs, while sf browserforce plugins list and schema.json point it to its raw URL on GitHub.

Screenshots and use cases

Below the description, the page shows the screenshot of the setting, where a numbered pill marks the control of each field, then its use cases, hand-written in src/plugins/<folder>/use-cases.md (one ## heading, story and config per use case). The screenshot is taken by a step of the E2E test, tagged @capture in its title and wrapped by capture() from test/capture.ts: it('should enable @capture', capture(mySettingSchema, { config, pages })). Each capture of pages (named screenshot when there is only one; it is the file name of the image) lists the selector of each field (reuse the selectors of the plugin) in the page that retrieve() of the plugin opens, or, when it opens none to show, the page an open(doc) function opens. It is shot after the step, or before it with screenshot: 'before'. .claude/skills/document-setting/references/capture.md describes the format in full.

npm run test:e2e runs the step like any test. With CAPTURE=true, it also takes the screenshots, in a scratch org only (never your default org):

npm run test -- -g "screenshots"                                                        # check the screenshots, without an org
CAPTURE=true SF_TARGET_ORG=browserforce-docs npm run test:e2e -- -g MySetting           # draw the images in src/plugins/my-setting/

The capture draws the numbered pills into the images right away; moving a pill (positions) means capturing again. A unit test checks that every setting has a screenshot, that its pills are fields of the setting and that its images exist. With Claude Code, /document-setting mySetting does all of this, including the scratch org.

Multi-line descriptions are written as an array of lines joined with '\n' (an indented template literal would turn them into code blocks). Then regenerate the pages and commit what changed in docs/, mkdocs.yml and README.md:

npm run generate:docs

It also writes docs/llms.txt (llms.txt, served at the root of the site): the pages a coding agent should read, from the navigation and the front matter of each page. It builds the plugin, generates the command pages with sfdx-hardis (installed in the .sf-docs-tooling folder, not in your sf), then the settings pages. It needs the sf CLI and bash (Git Bash on Windows). CI warns when the committed pages differ from the generated ones (the site is published from the regenerated pages anyway). To preview the site:

pip install -r docs/requirements.txt
zensical serve

The site looks like the Salesforce Lightning Design System, as SF Plugin Explorer: its colors are the --bf-* variables at the top of docs/stylesheets/extra.css, and mkdocs.yml sets the palettes (primary: custom, accent: custom, light and dark) and system fonts (font: false).

The other pages of docs/ (installation, configuration, troubleshooting, Hall of Fame) are written by hand. Do not edit the generated ones: they start with a comment saying so. Every page starts with a YAML front matter giving its title and its description (160 characters at most) for search engines; the generators write it for the generated pages, and a unit test fails when a hand-written page has none:

---
title: Troubleshooting
description: Fix a missing browser, watch or record what Browserforce does in Salesforce Setup with Playwright traces.
---

Implementation (index.ts)

Plugins are written in Typescript, just like sf and most of the available sf plugins.

Playwright is being used as a library for browser automation. If you need more inspiration regarding Playwright, checkout the official documentation and our best practices guide.

The simplified browserforce plugin lifecycle can be described as follows

pseudo code

currentState = retrieve()
plan = diff(currentState, userconfig)
if (plan) {
  apply(plan)
}

text

Retrieve the current state from the org (using browser automation or any available API that helps).

Compare the current state with the target state (user config) and determine necessary actions (plan).

Apply the given actions of the plan (described as JSON schema) if there are any.

Your plugin is required to implement the retrieve and apply function. In most cases, you don't have to implement diff yourself.

Now, this concept might seem superfluous at first, but it is important as it enforces idempotency: The execution will apply as few changes as necessary and so you will be able to re-execute the apply command leading to the same result without any failure.

Both the result of the retrieve function and the argument of the apply function are objects in the format defined by your schema. In this example, you would return {enabled: boolean} as part of retrieve, and expect {enabled: boolean} as argument in apply.

Formatting

After plugin development is completed, run the following command to ensure your code adheres to the project's style guidelines:

npm run format

This will automatically format your TypeScript and configuration files (e.g., indentation, line breaks, trailing commas) to maintain consistency across the codebase.

Testing

To run unit tests:

[!NOTE] Make sure to run these commands in your sfdx-browserforce-plugin directory.

npm run test

To run end to end tests:

[!CAUTION] Your default scratch org will be used in the E2E tests!

npm run test:e2e -- -g "AdminsCanLogInAsAnyUser" # will only run tests matching `AdminsCanLogInAsAnyUser`

[!IMPORTANT] E2E tests should be implemented to be re-runnable.

Please run the test at least 7 times to reduce the risk of a flaky implementation:

for i in {1..7}; do npm run test:e2e -- -g "AdminsCanLogInAsAnyUser"; done

Debugging

The Salesforce CLI Plug-In Developer Guide describes debugging sfdx plugins using VS Code very well.

Playwright Debugging and Tracing

When developing or debugging Playwright-based plugins, you have several tools at your disposal:

Visual Debugging

To see the browser while tests run:

BROWSERFORCE_HEADLESS=false npm run test:e2e -- --grep "YourPlugin"

To slow down execution for better observation (value in milliseconds):

BROWSERFORCE_SLOWMO=1000 npm run test:e2e -- --grep "YourPlugin"

Playwright Tracing

Playwright tracing captures detailed information about test execution including screenshots, DOM snapshots, network activity, and console logs. This is invaluable for debugging test failures.

To generate a trace for a specific test:

BROWSERFORCE_TRACE=true npm run test:e2e -- --grep "YourPlugin"

After the test completes, a trace file will be saved with a timestamp (e.g., trace-2025-11-23T19-00-00-000Z.zip).

To view the trace:

npx playwright show-trace trace-2025-11-23T19-00-00-000Z.zip

This opens an interactive viewer in your browser where you can step through each action, view screenshots and DOM snapshots, inspect network requests, and review console logs.