Block types / entry points

Summary

We currently provide that blocks can be exposed to applications in three different ways: as custom elements, HTML files, or React components.

This gives more freedom to block developers at the cost of additional complexity for embedding applications and in the specification.

We might alternatively specify one single permitted way in which blocks can be defined, which might be either:

(a) as a custom element, or

(b) as an HTML file which must be loaded as the source of an iFrame

Block authors could still use any other technology or library they wished to inside those definitions.

We could alternatively expand the current list of permitted entry points, for example to introduce blocks defined as HTML files which must be loaded as the source of an iFrame. These blocks would own their global scope and could be loaded from and rely on executing in a specific origin, which would make writing certain types of blocks easier.

We do not propose to make any changes at this stage, but will keep the current approach under review based on community feedback and how people write blocks in practice. If we intend to propose change, we will introduce a formal RFC.

Current approach

Version 0.2 of the Block Protocol specification provides for three different type of block “entry point”. By “entry point”, we mean what exactly the block source presents for the embedding application to interact with. The three currently listed are:

• custom-element: the block source file exports a CustomElement class
• html: the block source file is an HTML file
• react: the block source file exports a React component

This is an improvement on the original Block Protocol specification, which floated the idea of there being a limited number of entry points for blocks, without actually specifying them:

embedding applications will need to have strategies for handling blocks which are implemented in different ways … There must be some way of applications identifying how each block should be rendered. This might be achieved via inference from the block's source (e.g. the extension of its entrypoint), or by an explicit property in a block's metadata file. Either approach will require a small number of known, agreed 'block implementation approaches' which can be identified and handled. – Block Protocol v0.1

The provided tooling was also React-centric, and provided no support for anyone looking to write blocks using different approaches. We now provide block templates for each of the three block types which are defined in the specification (available via the create-block-app package).

These changes move this important topic along, but we do not believe it to be resolved.

Problems with the current approach

1. Having multiple types of entry points means more complexity in:
   1. the specification, and
   2. loading blocks
2. The current list of entry points does not capture all the ways in which developers may wish to define blocks, and adding more entry points would further increase complexity. Although other types of blocks can be written using the existing types as wrappers, this would also be true with a single block type.

Alternative: a single entry point

Alternatively, we might specify a single valid entry point for blocks.

Benefits

• reduce complexity in the specification as only one type of block would need to be accounted for (e.g. in describing how blocks should be loaded)
• reduce the burden on embedding applications in dealing with different types of blocks
• reduce the potential for fragmentation of the block ecosystem based on block type

Costs

• no choice for block authors in how the outermost layer of the block is defined (but with the freedom to use other approaches within the block)
• no choice for embedding applications as to what types of block they load
• any downsides specific to the entry point chosen

What would the single entry point be?

We believe that if the Block Protocol required all blocks to be defined using a single type of entry point, that it should be a native web technology, to ensure that blocks are compatible with as many embedding applications as possible, and to avoid tying the protocol to a framework or library that may be shorter-lived. This implies either:

• an HTML file, which loads its own scripts which can then call other libraries and technologies as required
• a custom element class, which can call other libraries and technologies as required within its constructor

HTML block

Under this option, the entry point for blocks would be an HTML file which included in-line scripts or loaded other scripts as required.

There are two variations on this approach:

1. The current html block type, which is expected to function whether the block is loaded in a sandbox or not
2. A version where blocks must be sandboxed, in which case the HTML file would be loaded as the source of an iFrame, and include code to handle making requests of the embedding application via postMessage (rather than via dispatching custom events as in the current spec)

Our initial view is that HTML files without compulsory sandboxing would not be a good choice for the only permitted entry point for blocks. They require much more care from block authors to avoid polluting the global scope (including potentially hard-to-avoid issues such as clashing dependency versions), and complicated script manipulation to enable blocks to locate themselves in the DOM. While we view these issues as acceptable as an option for block authors who want or need to write HTML blocks, we do not want to force them on all block authors.

On the other hand, HTML blocks which must be sandboxed as the only block type would eliminate all scope-sharing issues. The downside would be that compulsory sandboxing would rule out any future block functionality which depended on or was vastly improved by synchronous communication with the embedding application, as well as being a performance hit for applications that would otherwise load some or all blocks outside a sandbox.

We considered introducing ‘compulsorily sandboxed HTML blocks’ as part of Block Protocol 0.2, but decided not to as it would introduce even more branching into the specification (to describe rendering and message passing via an iFrame).

With respect to these types of blocks, we have three options:

• Do nothing: having no compulsorily sandboxed HTML blocks (the current position) makes it more cumbersome to write blocks that own a scope or use a specific origin, as they must load their own iFrame to do so. Writing HTML blocks also involves additional steps for both the embedding application and block author, in order for the block to be able to identify itself, and more care from the block author to avoid polluting the global scope.
• Enforce as the only block type: this would eliminate a class of problems related to blocks sharing a scope with other JavaScript and CSS, by virtue of and at the expense of requiring all blocks to be sandboxed, which may impact performance for applications that would otherwise leave trusted blocks un-sandboxed, and would rule out potential future functionality that required synchronous communication between block and embedding application.
• Add as an alternative: this would provide better first-class support in the specification for blocks that wish to be guaranteed their own scope or origin, at the expense of introducing more complexity to the specification in order to handle yet another type of block.

Custom element

Custom elements – part of the Web Component technologies – offer a native way of defining encapsulated components.

Under this option, all blocks would be defined as a custom element class with an associated tag name, and registered by the embedding application using that class and name, as per the current custom-element entry point in the specification.

Block authors wanting to use a different approach could load their tools of choice within the custom element definition (e.g. render a React component).

Way forward

We will be writing blocks using the different entry points permitted in the current Block Protocol, to explore how different approaches fare for different use cases, and the issues that different entry points present in real-world usage.

We also seek views from the community, and evidence on what sorts of blocks people want to and actually do write in practice, before making any further changes to the specification, whether to add block types or to specify only a single permitted block type.

We want to strike a balance between making the Block Protocol as widely usable and attractive as possible, while minimising the complexity in the specification and for its implementers.