Portal
Drop-in script to make the bulk of Ghost membership features work on any theme.
Usage
Ghost automatically injects the Portal script on all sites running Ghost 4 or higher.
Alternatively, Portal can be enabled on pages outside Ghost by adding this script:
<script defer src="https://unpkg.com/@tryghost/portal@latest/umd/portal.min.js" data-ghost="https://mymemberssite.com"></script>
The data-ghost attribute expects the URL for your Ghost site, which is the only input Portal needs to work with your site's membership data via Ghost APIs.
Custom trigger button
By default, the script adds a default floating trigger button on the bottom right of your page which is used to trigger the popup on screen.
You can add a custom trigger by adding the data-portal attribute to any HTML
element. Set its value to choose a specific
Portal page,
for example data-portal="signup".
Share modal can be opened with data-portal="share" (or #/share).
Default (zero-config) usage:
<button type="button" data-portal="share">Share</button>
On pages where {{ghost_head}} is rendered, Portal will auto-resolve metadata from DOM tags:
- URL: canonical URL (or current URL fallback)
- Title: Open Graph title (or document title fallback)
- Image: Open Graph image (or Twitter image fallback)
Troubleshooting missing preview metadata:
- Verify the template includes
{{ghost_head}}. - Verify rendered HTML contains canonical + OG/Twitter tags.
The script adds gh-portal-open and gh-portal-close classes to custom triggers
to reflect the popup state.
See the Portal settings documentation for ways to customize Portal for your site.
Develop
Run Portal's build watcher with the other public apps from the monorepo root:
pnpm dev:public
Portal rebuilds as you edit and is served at
http://localhost:2368/ghost/assets/portal/portal.min.js, which theme pages on
the development site load. pnpm dev serves the build from when it started.
Build
From this directory, create a production minified bundle in
umd/portal.min.js with:
pnpm build
Test
From this directory, run unit tests once or in watch mode with:
pnpm test
pnpm test:watch
Ghost e2e tests
Portal is primarily tested through Ghost's Playwright tests in the e2e/
directory. Run them from the monorepo root:
pnpm test:e2e
Release
Patch releases are automatic. When Portal changes on main, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
If you're releasing new code that should not immediately go live always use a minor or major version when publishing.
For an intentional minor or major release:
- From a clean branch, run
pnpm shipand select a minor or major version - Merge the release commit to
main - Wait for a public Ghost release to ship the new default version line
pnpm ship updates both the package version and Ghost's default Portal version.
Copyright & License
Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.