Installation

Install the CLI, set up the local services and add the loader with a pinned version.

Requirements

• macOS. Windows and Linux are not supported yet.
• Node.js 18 or newer.
• Homebrew.

Install the CLI

$ npm install -g @stagepass/cli
$ stagepass --version

Set up the local services

stagepass setup runs once per Mac:

1. Checks that Homebrew is installed.
2. Installs Caddy, PHP and Dnsmasq with Homebrew.
3. Points every .sp name to 127.0.0.1 in Dnsmasq.
4. Writes /etc/resolver/sp so macOS asks Dnsmasq for .sp names. This step asks for your password.
5. Restarts Dnsmasq and flushes the DNS cache.

$ stagepass setup
$ stagepass start

stagepass start asks for your password, because Caddy serves HTTPS on port 443.

Check the result with stagepass doctor. It is read only and never uses sudo. To start the services at login, run stagepass autostart on. See CLI.

Add the loader and modules

Load the packages from jsDelivr with the major pin @2:

<script src="https://cdn.jsdelivr.net/npm/@stagepass/loader@2/dist/loader.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@stagepass/modules@2/dist/inject.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@stagepass/modules@2/dist/cookies.min.js"></script>

Prefer to serve the files from your own host? See Self-host the files.

Version pinning

Use the major pin @2. An exact version like @2.3.0 is an option if you want full control.

Optional exact pin

For maximum control (freeze one publish), use an exact version such as @2.3.0:

<script src="https://cdn.jsdelivr.net/npm/@stagepass/loader@2.3.0/dist/loader.min.js"></script>

Legacy 1.x (still valid if you pin it)

Sites that keep @1 / exact 1.x pins are unaffected by 2.x:

<script src="https://cdn.jsdelivr.net/npm/@stagepass/loader@1.2.0/dist/loader.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@stagepass/modules@1.1.0/dist/inject.min.js"></script>

Why @2:

• Compatible updates: minor/patch releases within v2 stay backward compatible under strict semver.
• One intentional major bump: breaking changes require a new major (v3) and a deliberate URL change.
• Cache: jsDelivr may cache @2 for a while after a release. A new minor can take some time to reach your site.
• Exact pin when needed: use @2.3.0 (or any exact version) for maximum control; prereleases are never resolved by @2.

Self-host the files

The CDN is the default. You can also install the packages with npm and serve the files from your own host.

$ npm install @stagepass/loader@2 @stagepass/modules@2

Copy these files from node_modules to your host:

Then point the tags to your host. Keep the loader first:

<script src="https://assets.example.com/stagepass/loader.min.js" defer></script>
<script src="https://assets.example.com/stagepass/inject.min.js" defer></script>

• Modules have no lookup of their own. Each one is a normal script tag after the loader.
• stagepass doctor and stagepass upgrade detect modules on the live site only from public npm CDN URLs. On a self-hosted site, pass the list with stagepass upgrade --site-modules inject,cookies and use stagepass doctor --skip-site.
• Pin the version in your package.json and update on purpose: npm install @stagepass/loader@2.3.0. Copy the files again after every update.

CDN or self-hosted

Remove Stagepass

$ stagepass stop
$ npm uninstall -g @stagepass/cli

Your settings stay in ~/.stagepass/ until you delete the folder. Remove the loader tag from Webflow and publish to take it off the site.