@playstack/extension

MV3-safe authentication, typed messaging, validated storage, permissions, and refresh coordination for browser extensions.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/extension supplies runtime primitives for a Playstack-connected Manifest V3 extension. WXT owns scaffolding, entrypoints, manifests, bundling, and store builds; Playstack owns boundaries that must survive a disposable service worker.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/extension@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose authentication

import { createClientAuth } from '@playstack/client-auth'
import {
  createExtensionAuthorizationLauncher,
  createExtensionTokenStorage,
  createWebLockRefreshCoordinator,
} from '@playstack/extension'

const auth = createClientAuth({
  clientId: 'browser-extension',
  authorizationEndpoint,
  redirectUri: browser.identity.getRedirectURL(),
  scopes: ['profile'],
  transport,
  launcher: createExtensionAuthorizationLauncher(browser.identity),
  storage: createExtensionTokenStorage({
    session: browser.storage.session,
    local: browser.storage.local,
  }),
  refreshCoordinator: createWebLockRefreshCoordinator(navigator.locks),
})

Short-lived access credentials live in session storage. Refresh credentials live in local storage, while a Web Lock serializes rotation across popup, content-script, and service-worker contexts. The extension opens the application’s existing browser authorization flow and never receives a user’s password.

Messaging, storage, and permissions

defineMessages() validates request and response payloads around typed runtime handlers. defineExtensionStorage() and createExtensionStorage() validate values every time they cross browser storage. ensureExtensionPermissions() checks existing optional permissions before prompting and fails explicitly when the user declines.

All APIs are structural: pass the browser facade supplied by WXT or another extension runtime without importing that framework into Playstack.

Boundary

Module memory and timers are never durable MV3 state. Register browser event handlers at module evaluation, reconstruct state on wake, and use alarms for long delays. @playstack/lint supplies explicit extension presets for remote code, long worker timers, and mutable worker-memory state.

API entry points and requirements

Reference snapshot: @playstack/extension@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry point	Declaration file
`@playstack/extension`	`./dist/index.d.ts`
`@playstack/extension/auth`	`./dist/auth.d.ts`
`@playstack/extension/messaging`	`./dist/messaging.d.ts`
`@playstack/extension/permissions`	`./dist/permissions.d.ts`
`@playstack/extension/storage`	`./dist/storage.d.ts`
`@playstack/extension/playstack.integration.json`	No TypeScript declaration (asset or metadata export).
`@playstack/extension/package.json`	No TypeScript declaration (asset or metadata export).

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.