Runtime Messages API

Extension contexts (popup, content script, background, main dashboard) run in isolated JavaScript environments. They communicate via the browser's runtime messaging API.

LightningAddon defines a typed RuntimeMessageMap in @repo/core so every message and response is type-checked at compile time.

Message Types

Message	Payload	Response
PING	void	{ ok: true; source: 'background' }
GET_INSTALL_REASON	void	{ reason: string }
SET_INSTALL_REASON	{ reason: string }	{ ok: true }
CREATE_CHECKOUT	{ email: string; subType: 'monthly' | 'yearly' }	{ url: string } | { error: string }
CREATE_PORTAL	{ customerId: string }	{ url: string } | { error: string }
GET_PROFILE	void	{ isPaid: boolean; stripeCustomerId: string | null }

Usage

Sending from UI (popup, main, in-page):

import { sendRuntimeMessage } from '@repo/core';

const profile = await sendRuntimeMessage({ type: 'GET_PROFILE' });
// profile is typed: { isPaid: boolean; stripeCustomerId: string | null }

Listening in background:

import { addRuntimeMessageListener } from '@repo/core';

addRuntimeMessageListener({
  GET_PROFILE: async () => {
    // fetch profile from backend
    return { isPaid: false, stripeCustomerId: null };
  },
});