Skip to content

v4.0.0
Compare
Choose a tag to compare
@Aaronius Aaronius released this 15 Apr 03:59
· 122 commits to master since this release
v4.0.0
78ba6f9

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

Browser Support

What

Internet Explorer support has been dropped. As such, support for providing a promise implementation by setting Penpal.Promise has been removed.

Why

Internet Explorer browser share worldwide is ~2.5%. Because Penpal was being transpiled for Internet Explorer, the lowest common denominator, all consumers had to pay the penalty through larger bundle sizes. I also needed to save my sanity while debugging. If you're one of the unlucky souls that still needs to support Internet Explorer, you should feel confident continuing to use version 3.x of Penpal.

Importing

What

When using a bundler, import connectToChild as follow:

import connectToChild from 'penpal/lib/connectToChild';

and import connectToParent as follows:

import connectToParent from 'penpal/lib/connectToParent';

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

import {
  ERR_CONNECTION_DESTROYED,
  ERR_CONNECTION_TIMEOUT,
  ERR_NOT_IN_IFRAME,
  ERR_NO_IFRAME_SRC
} from 'penpal/lib/errorCodes';

Why

By only importing the functionality you need, you can keep your builds slimmer.

Iframe Creation

What

Previously, Penpal would typically create the iframe, set the src property, and add the iframe to the document on your behalf. This is no longer the case. You will need to create the iframe, set the src property, and add the iframe to the document. Then, pass the iframe to Penpal.

Consequently, the url and appendTo options have been removed from connectToChild while the iframe option is now required. The connection object returned from connectToChild no longer contains an iframe property since you already have direct access to the iframe you created.

Why

The connectToParent API had become increasingly complex and was becoming even more complex with newly added support (new in v4!) for the iframe srcdoc property. Having Penpal create the iframe wasn't providing sufficient value to overcome the additional complexity required to support it.

Debugging

What

Rather than setting Penpal.debug, you can enable debugging by passing a debug option to connectToChild or connectToParent.

Why

Since you're now importing connectToParent and connectToChild directly when using a bundler, there is no Penpal object.

Error Codes

What

The ERR_IFRAME_ALREADY_ATTACHED_TO_DOM error code has been removed. A new error code, ERR_NO_IFRAME_SRC, has been added. It will be thrown if the iframe provided to Penpal does not already have its src or srcdoc property set.

Why

Penpal is no longer responsible for appending the iframe to the document. You may append the iframe to the document before or after connectToChild has been called. The only requirement is that connectToChild is called from the parent before connectToParent is called from the child.

TypeScript Declarations

What

TypeScript declarations have been removed from the project.

Why

As outlined in the TypeScript documentation, when a project is not written using TypeScript, it is preferred to publish TypeScript declarations to the @types organization on npm instead of bundling them with the library. Another reason is that I don't use TypeScript generally, making it difficult to update the declarations accurately as changes are made in the library. If you liked the declarations that were available, I would encourage and appreciate it if you would add them to the @types npm org.

Support for srcdoc and data URIs.

What

You don't actually have to change anything here, because neither of these things were previously supported. I just wanted to make you aware that, if it applies to you, you can now set the src property of the iframe using a data URI or leverage the iframe's srcdoc property instead.

Why

These use cases were becoming more common.

Assets 2
Loading