# Block Protocol for building and embedding data-driven blocks

> Block Protocol is an open standard and TypeScript monorepo for developing blocks and integrating them into applications without requiring direct knowledge of one another. Its libraries cover the core contract, graph operations, hooks and a WebAssembly-based type system, but the repository provides little standalone installation guidance.

**blockprotocol/blockprotocol** — ✨ The open-source standard for blocks. From @hashintel

- Repository: https://github.com/blockprotocol/blockprotocol
- Website: https://blockprotocol.org
- Stars: 1,438 · Forks: 48
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/blockprotocol-blockprotocol

## Block Protocol's application and block boundary

Block Protocol addresses a coordination problem between two parties that may never share a codebase or know one another. A block developer creates a data-driven interface, while an application developer makes that interface available inside an editor, page or other runtime. The README states that neither side needs knowledge of the other application's existence. Each only needs to conform to the protocol.

That boundary makes Block Protocol different from a shared component library. A conventional component library requires the host application to choose the component, import its package and connect its props. A protocol-based block can be treated according to the common contract by an embedder, without the two implementations being compiled as one product. The protocol documentation also separates three development paths: creating and publishing a block, using blocks in an application, and becoming an embedder for other people's blocks.

The intended users are therefore both sides of that boundary. Application teams need a common model for inserting blocks at runtime. Block authors need a documented way to expose behavior and data without depending on one embedding product. The repository also names HASH and WordPress as supported examples. The WordPress integration is associated with a Block Protocol plugin, while HASH is described as an embedding application that allows users to insert arbitrary blocks from the Þ Hub at runtime.

## Core, graph, hook and type-system modules

The repository is organized as a monorepo rather than as one deployable application. Its workspaces include `infra/*`, `libs/@blockprotocol/*`, selected paths under `libs`, and `blocks/*`. That structure reflects the protocol's two-sided architecture, although the cleaned README only explicitly describes the library and block paths.

Four published library families define the main technical surface. `@blockprotocol/core` implements the Core specification for blocks and embedding applications. `@blockprotocol/graph` implements the Graph module, which is the repository's named mechanism for graph-oriented data operations. `@blockprotocol/hook` implements the Hook module, providing the protocol surface for hooks. `@blockprotocol/type-system` implements the type system as a WebAssembly base. The README does not provide API signatures, payloads or lifecycle details for these modules, so those details must be checked in the linked Core, Graph and Hook specifications.

For engineers, this modular split is the main design decision. An integration can begin with `@blockprotocol/core`, then add `@blockprotocol/graph` only if the block actually needs the corresponding graph contract. The existence of separate packages does not prove that every embedding application must load all four. The repository presents them as implementations of distinct specification modules, but the exact compatibility requirements for a particular use case are not documented in the root README.

## Installing a Block Protocol library

The root README does not give a complete package installation tutorial. It directs readers to the Block Protocol documentation for complete instructions and says that libraries in `libs` can be added with `yarn add <package_name>` or `npm install <package_name>`. The root package manifest also establishes a Yarn workspaces monorepo, but it does not document a release tag or installation command for a ready-made host application.

A first real use therefore begins with identifying which side of the protocol you are building. For a block author, open the linked `developing blocks` documentation, choose the applicable library, and follow its package-specific installation instructions before building or publishing to the Þ Hub. For an application developer, follow the `becoming an embedder` documentation and inspect the protocol requirements for the target environment. The documentation also has a separate WordPress environment page and identifies the Block Protocol for WordPress plugin as the integration used there.

For contributors working inside the repository rather than installing a package, the root `package.json` defines `prepare` as a combined patch, code generation and build operation, along with separate `lint`, `lint:tsc`, `lint:eslint` and `lint:prettier` scripts. These are repository maintenance commands, not a consumer setup path. The README does not document required Node.js or Yarn versions, required environment variables, browser support, or a first-use example that can be copied without consulting the linked documentation.

## Choosing an embedder path for a first integration

A concrete adoption check starts by mapping the desired runtime to one of the documented environment paths. If the target is HASH, the README says that HASH can insert arbitrary Þ Hub blocks at runtime. If the target is WordPress, the documented path is the Block Protocol for WordPress plugin. For another application or framework, the README links to the `other environments` guidance under the Block Protocol environment documentation.

That distinction matters because Block Protocol is not itself described as the editor, host application or block registry. It is the standard implemented by those components. An application team still needs to determine how blocks are discovered, inserted, rendered and removed in its own product. A block team still needs an environment in which to develop and a publication path if the block is intended for the Þ Hub.

The root README does not explain whether a private block registry is supported, how an embedder verifies compatibility between a block and its runtime, or what offline behavior looks like. It also does not provide a minimal host implementation in the repository overview. Those are adoption gates rather than details that can safely be inferred from the presence of TypeScript packages.

## Operational limits of the repository documentation

The clearest limitation is the gap between a public protocol ambition and the amount of integration detail exposed by this repository overview. The README links to specifications and external documentation, but it does not document version negotiation, error behavior, permissions, sandboxing, resource limits, accessibility requirements or migration rules. It also does not explain what an embedder should do when a block expects a Graph or Hook capability that the host does not support.

Block Protocol may be the wrong choice for an application whose only requirement is to import a React component at build time. In that case, the package boundary is known, the props are explicit and there is no need for runtime interchange with unknown blocks. Protocol adoption introduces a compatibility boundary, specification work and more separate integration surfaces. An application that does not need that separation would gain little from the `@blockprotocol/core`, `@blockprotocol/graph` and `@blockprotocol/hook` model.

The package split also creates a deliberate maintenance surface. Consumers need to track the versions of whichever protocol libraries they use and the specification expectations of their blocks. The repository's recent published packages include `block-template-react@0.4.6`, `block-template-html@0.3.6` and `mock-block-dock@0.1.10`, all released on 2024-03-19. Those dates do not establish current compatibility by themselves, but they show that the visible release list and the repository activity date should be reviewed separately.

## Block Protocol compared with direct component embedding

The practical alternative is direct embedding of a known component or application-specific block interface. That approach binds the host and block through a shared package API, an agreed component contract or framework-specific props. It can be simpler when the host controls both repositories and the block is never moved between environments. TypeScript props, bundler configuration and framework lifecycle rules remain local to the integrating organization.

Block Protocol uses conformance to a published standard instead. Its core library represents the common block and embedding contract, while optional modules address graph behavior and hooks. The type-system package supplies a WebAssembly-based type layer. This approach fits a marketplace or editor scenario in which blocks arrive at runtime and the host cannot assume prior knowledge of their implementation.

The trade-off is interoperability against control. Direct embedding can offer a narrow, locally enforced API. Protocol embedding requires both sides to understand the same specification and compatible module behavior. The README does not claim that every block will work in every environment. Its named environments and module-specific documentation indicate a compatibility model that still requires explicit verification for the chosen runtime.

## Maintenance, licensing and upgrade checks

The repository is not archived, and its last push was on 2026-09-11. The release dates visible for the named packages are older, so commit activity and package release cadence should not be treated as the same signal. The repository contains `.changeset/`, `turbo.json`, a `yarn.lock`, lint scripts and a `prepare` script that runs patching, code generation and builds. Based on that layout, maintainers must account for changes across packages and workspace dependencies rather than updating one isolated directory.

The project uses a custom license identified as `LICENSE.md`, not a standard SPDX label in the repository metadata. The available text does not state its permissions, restrictions, attribution obligations or redistribution conditions. Those details must be read before using a library, publishing a derived block, or distributing an embedding application. This article cannot determine whether a particular commercial model is permitted.

Before upgrading, check the package version and the linked specification version together. Then confirm which `@blockprotocol` modules the integration actually uses, inspect any migration notes for those packages, and review the license changes. The root README does not provide a formal support matrix or a promise of backward compatibility.

## Conclusion

Adopt Block Protocol when an application must accept independently developed blocks through a common contract, or when a block must run in multiple compliant environments. Do not choose it merely because the application needs ordinary React components, or adopt the libraries until you have checked the custom LICENSE.md and validated the relevant specification and module against your integration. For this repository specifically, the first verification should be whether the documented embedding contract fits your application boundary and whether the custom license permits your intended distribution.

## FAQ

### What is Block Protocol used for?

It is an open standard for building, using and embedding data-driven blocks. A block and an embedding application can conform to the protocol without knowing one another's implementation.

### Which Block Protocol packages are listed in the repository?

The README lists `@blockprotocol/core`, `@blockprotocol/graph`, `@blockprotocol/hook` and `@blockprotocol/type-system`. The first three implement named protocol modules, while the type system is described as WebAssembly-based.

### How do I install a Block Protocol library?

The README says libraries in `libs` can be installed with Yarn or npm, but it does not give package-specific commands or versions in this repository overview. It directs users to the Block Protocol documentation and the individual library READMEs for complete instructions.

### Can Block Protocol blocks run in WordPress?

The README says WordPress supports embedding Þ blocks through the Block Protocol for WordPress plugin. It also identifies HASH as an embedding application and links to guidance for integrating other environments.

### What license does blockprotocol use?

The repository metadata identifies the license as a custom license in `LICENSE.md`.

## Sources

- [blockprotocol/blockprotocol on GitHub](https://github.com/blockprotocol/blockprotocol)
- [Issues](https://github.com/blockprotocol/blockprotocol/issues)
- [Project website](https://blockprotocol.org)
- [README](https://github.com/blockprotocol/blockprotocol/blob/main/README.md)
- [Releases](https://github.com/blockprotocol/blockprotocol/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blockprotocol-blockprotocol