Developing Blocks

The quickest start

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.

Almost-as-quick start

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:

Install

1. Move to a folder where you want to create your block
2. Run npx create-block-app [your-block-name] or yarn create block-app [your-block-name]
3. Switch to your new folder: cd [your-block-name]
4. Run yarn install && yarn dev
5. Open http://localhost:63212 in your browser. You should see ‘Hello World!’

Code

Edit src/app.tsx to change the behavior of your block.

The 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 dev.js.

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 AppProps.

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 linkGroups.

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.

The 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:

• embedding applications may provide some styleVariables for use - see styling - which you should use where appropriate, and if defined. See also: Design guidelines for developing blocks
• you can include dependencies in your block, but keep in mind bundle size. Common dependencies which you can reasonably expect an embedding application to provide (e.g. React) can be defined as externals/peerDependencies - see the template README.

Build

Once you’ve finished writing your block, run yarn build.

This will produce a compiled version of your code in the dist folder, along with metadata files describing your block (block-metadata.json), and the data it accepts (block-schema.json).

It is worth updating the blockprotocol object in package.json to include your own icon, image, and examples for your block. These will automatically be included in the block-metadata.json produced after running yarn build.

You now have a block package that you can provide to apps to use, by publishing it on the Block Hub.

Publish

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!

Other approaches

I don’t want to use TypeScript

You can write your block in regular JavaScript using the method described above - just rename your app to App.jsx, remove the types, and get coding - but the block schema will not be automatically generated as part of the build process.

You can write your own block schema manually, giving the type of props your App component accepts in JSON Schema format.

I don’t want to use React

We will be releasing examples of how to write blocks using different web technologies and frontend libraries in the near future.