Releases: Aaronius/penpal
v5.0.2
v5.0.1
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.
v4.1.1
v4.1.0
v4.0.0
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.