v5.0.0

With a major release comes breaking changes. Here's what you need to know:

Importing

What

When using a bundler, import connectToChild as follow:

import { connectToChild } from 'penpal';

and import connectToParent as follows:

import { connectToParent } from 'penpal';

If you're importing error codes, import them as follows:

import { ErrorCode } from 'penpal';

// Reference individual error codes as follows:
// ErrorCode.ConnectionDestroyed
// ErrorCode.ConnectionTimeout
// ErrorCode.NotInIframe
// ErrorCode.NoIframeSrc

Why

Penpal no longer ships with ES5. The ES6 code is set up in such a way that your bundler of choice should properly tree shake unused code. Your bundler, when properly configured, should also perform any transpilation necessary for your browser targets.

EDIT July 8, 2020: As of v5.1.0, ES5 is again included in the npm package, alongside ES6. Bundlers should automatically use the appropriate version.

Regex Support for parentOrigin

What

When using connectToParent, you can now specify a regular expression for parentOrigin. By providing a regular expression, you can now load the iframe onto multiple, different domains while ensuring that communication is secured to those domains only.

Why

This need has been raised several times in the past and was a fairly common use case. While this was not a breaking change, it did require significant changes to the handshake process as described in #32 (comment) and due to the higher risk of the change I decided to include it with other breaking changes in v5 rather than adding it to v4.

TypeScript

What

Penpal is now built using TypeScript, so if you're using TypeScript, you now get types for free!

Why

Consumers wanted TypeScript typings and I thought the positive qualities of TypeScript would enhance the Penpal development process.