Contributing

Build, test and improve Stagepass. Issues and pull requests are welcome.

Get the code

Stagepass is open source under the MIT license. Issues and pull requests are welcome. The repository is a monorepo with npm workspaces for cli, loader and modules.

$ git clone https://github.com/arobertherz/stagepass.git
$ cd stagepass
$ npm install
$ npm run build

Prerequisites

• Node.js 18+
• npm (comes with Node.js)
• macOS only
• Homebrew (for dependency management)

Local development setup

1. Install Dependencies

Install all workspace dependencies from the root directory:

$ npm install

This downloads all packages for CLI and Loader and links the workspaces.

2. Make CLI Executable

Make the CLI binary executable:

$ chmod +x packages/cli/bin/index.js

3. Link CLI Locally

Link the CLI package to simulate a global installation:

$ cd packages/cli
$ npm link

Note: This may require sudo depending on your Node.js installation, but usually it's not needed.

After linking, you can use stagepass commands from anywhere:

$ stagepass setup
$ stagepass start
$ stagepass link my-project

4. Build Loader

Build the loader package:

$ cd packages/loader
$ npm run build

This generates dist/loader.js and dist/loader.min.js.

For development with watch mode:

$ npm run dev

Project structure

stagepass/
├── packages/
│   ├── cli/           # CLI tool (published as @stagepass/cli)
│   │   ├── bin/       # Executable entry point
│   │   └── src/       # Source code
│   │       └── commands/
│   └── loader/        # Browser loader (published as @stagepass/loader)
│       ├── src/       # TypeScript source
│       └── dist/      # Built files (committed for CDN)
└── README.md

Testing changes

Prefer running the full test run in Docker (host node_modules may be macOS-native):

$ docker run --rm -v "$PWD":/w \
  -v /w/node_modules -v /w/packages/cli/node_modules \
  -v /w/packages/loader/node_modules -v /w/packages/modules/node_modules \
  -w /w node:22-bookworm-slim bash -lc 'npm ci && npm run build && npm test --workspaces --if-present'

Also verify on Node 20 (node:20-bookworm-slim) to match CI. Loader v2 behaviour notes: session expiry, version cache busting, and no global console mute. See MIGRATION.md.

CLI Changes

After modifying CLI code, the changes are immediately available if you used npm link. No rebuild needed.

Loader Changes

1. Modify packages/loader/src/index.ts
2. Run npm run build in packages/loader/
3. Test the built dist/loader.min.js in your Webflow project

For quick iteration, use watch mode:

$ cd packages/loader
$ npm run dev

Unlinking

To unlink the CLI after development:

$ npm unlink -g @stagepass/cli

Or if you want to remove the global link:

$ cd packages/cli
$ npm unlink

Guidelines

• Open an issue first for larger changes, so we can agree on the approach.
• Keep features opt in and avoid breaking changes in minor versions.
• Add or update tests for what you change.
• Document changes in CHANGELOG.md.

Read the LICENSE and browse the open issues.