Getting started with Stagepass
Serve a local folder on a .sp domain and load it on your live Webflow site, only in your browser.
Requirements
- macOS. Windows and Linux are not supported yet.
- Node.js 18 or newer.
- Homebrew, used to install the local services.
$ npm install -g @stagepass/cli1. Set up your Mac
Run this once. It installs Caddy, Dnsmasq and PHP and configures the resolver for .sp domains.
$ stagepass setup
$ stagepass start2. Link a project
Go to the folder where your built files live, for example dist/ or js/.
$ cd my-awesome-project
$ stagepass link my-projectYour folder is now served at https://my-project.sp with valid SSL.
3. Add the loader
In Webflow, open Project Settings, Custom Code, Head Code and add the loader. Publish once.
<!-- Core loader, major pin @2 -->
<script src="https://cdn.jsdelivr.net/npm/@stagepass/loader@2/dist/loader.min.js"></script>4. Tag your files
Replace src or href with data attributes. Visitors still get the production URL.
<script
data-src="https://cdn.example.com/app.min.js"
data-stagepass="true"
data-stagepass-path="js/app.js"
></script>| Attribute | What it does |
|---|---|
data-src, data-href | The production URL, loaded for everyone by default. |
data-stagepass="true" | Turns Stagepass on for this element. |
data-stagepass-path | Path to the local file. Optional, otherwise the file name from the production URL is used. |
data-stagepass-v | In production, appends ?v=<value> so browsers load the new file after a deploy. Optional. |
All attributes and loader options: Loader and data-stagepass.
5. Start a session
Open your live Webflow URL and add the parameter once:
https://www.my-client.com/?stagepass=my-project.spThe loader keeps the session in localStorage for 12 hours, so you can reload and browse sub pages. A small flag in the top right corner shows the session. Hover it for the mode and the warning and error counters, click it for the session card. End session in the card disconnects. See Flag states.
Modes
| Parameter | Result |
|---|---|
?stagepass=my-project.sp | Local mode. Tagged files load from your .sp domain. |
?stagepass=debug | Debug mode. Logging only, no files are swapped. |
?stagepass=off | Off. Same as End session in the session card. |
Modules and CORS
Plain scripts and stylesheets work right away. During a session the loader loads local files with crossorigin="anonymous", so errors keep their message, line and stack. Allow your live site once, so your .sp domain sends the CORS header. This is required for type="module":
$ stagepass link my-project --origin www.my-client.com --origin my-client.webflow.ioWithout it, plain files load again without crossorigin and the session card shows a warning that error details are limited.