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:

1. Verify the template includes {{ghost_head}}.
2. 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

Portal runs automatically with Ghost's standard development command from the monorepo root:

pnpm dev

This starts Ghost, Admin, and Portal. Portal is served through the development gateway at http://localhost:2368/ghost/assets/portal/portal.min.js and loaded into theme pages on the development site. Use pnpm dev:public when changing Portal alongside the other public apps.

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:

1. From a clean branch, run pnpm ship and select a minor or major version
2. Merge the release commit to main
3. 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.