A quick start guide to developing blocks
Any valid HTML is already a block.
Got some HTML? Congratulations, you have a block. Go publish your block so that others can find and use it!
Do you want your block to interact with the application using it? Read on.
Blocks are discrete components that render information or provide functionality. You can create them using any web technology or framework. In our current examples, we use React, a ready-made library for writing components. If you need it, here’s an intro to React.
Note: you can define blocks without using React. We'll be expanding this section of the documentation soon with examples covering other approaches.
Blocks can be sent data by the apps using them. Blocks can tell apps what types of data they take. We suggest writing blocks in TypeScript, which helps describe types.
We’ve provided a template to help you get started - here’s how to use it:
npx create-block-app [your-block-name]or
yarn create block-app [your-block-name]
yarn install && yarn dev
src/app.tsx to change the behavior of your block.
AppProps type describes what data your block accepts - the names and types of properties that embedding applications
should pass to your block. You can pass in starting props for testing in
Embedding applications may also pass an
updateEntities function, an
entityId and an
entityTypeId as properties
to your block - these are the ids identifying your block data in the app. Call
updateEntities with any new data
you want the app to set for your block - it should match the data types you have defined in
You can see an example block using
updateEntities in the HASH repo.
There are other functions available to blocks:
createEntities to create new entities, and
createLinks to create links between them.
You can create links from your block to other entities, to have them loaded in the
linkedEntities field passed to your block on future loads - with the links themselves passed in
Using these functions in combination, you can create complex graphs from within a block, without having to know anything about the implementation details of the application embedding it.
create-block-app template includes a mock embedding application,
MockBlockDock, which passes mocks of these functions and maintains an in-memory datastore while you are running your block in development mode.
For more details on creating entities and links between them, read the specification.
Points worth noting:
peerDependencies- see the template README.
Once you’ve finished writing your block, run
This will produce a compiled version of your code in the
dist folder, along with metadata files describing your block (
and the data it accepts (
It is worth updating the
blockprotocol object in
package.json to include your own
examples for your block. These will automatically be included in the
block-metadata.json produced after running
You now have a block package that you can provide to apps to use, by publishing it on the Block Hub.
Once you've built your block, make sure to publish it on the Block Hub to show it off to the world, and claim your blockprotocol.org namespace!
You can write your own block schema manually, giving the type of props your App component accepts in JSON Schema format.
We will be releasing examples of how to write blocks using different web technologies and frontend libraries in the near future.