safe-frame-sync

Typesafe iframe and parent communication between Dotstudio and Dotclinic.

This library provides a Pub/Sub system for secure, typesafe communication between a parent host and an iframe, abstracting window.top.postMessage and window.onmessage. Events and corresponding payloads are typed to ensure error-free communication and improve developer experience.

Collaboration

Setup

Install dependencies with:

npm install

Build

To build the package, run:

npm run build

Publish

The package is published on npmjs.

npm run build
npm login
npm publish --access public

Usage

First, add the dependency to the project:

npm add @dotbase/safe-frame-sync

The package provides two essential functions:

• publishMessage for sending typed messages
• subscribeMessage for listening to specific typed messages

Message Types

In Parent

import { subscribeMessage } from "@dotbase/safe-frame-sync";

// Somewhere in your code
subscribeMessage("createResource", (data) => {
  // Your callback implementation with type-safe data
  console.log(data);
});

In Iframe

import { publishMessage } from "@dotbase/safe-frame-sync"

// Somewhere in your code
publishMessage({
    type: "createResource";
    resourceId: "some-uuid";
    resourceName: "Some Name";
    workflowType: "document";
})

Release Process

We are using Semantic Release and Github Actions to build and publish a new version of this package, whenever we merge something on the main branch.

We do not rely on a NPM_TOKEN as this is phased out by NPM. Instead we use Trusted Publishing, which is set up between our npm package and this repository and the publishing Github Action.

See .github/workflows/semantic-release.yml for the detailed implementation and the @dotbase/safe-frame-sync npm package settings for the Trusted Publishing settings.

Commit Message Format

Semantic Release inspects commit messages on main to decide which version bump to apply:

• feat: triggers a minor release.
• fix: triggers a patch release.
• Any commit that contains BREAKING CHANGE: (in the body or footer) triggers a major release, regardless of the type.
• Types such as chore:, docs:, refactor:, etc. do not trigger a release on their own.

Stick to the Conventional Commits format so releases stay automatic and predictable.