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¶
-
Fork this repository and clone your fork
-
Install dependencies
[!NOTE] Make sure to run these commands in your
sfdx-browserforce-plugindirectory.
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 ofsettings.<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:
. The documentation site shows a copy made bynpm run generate:docs, whilesf browserforce plugins listandschema.jsonpoint 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.