Defining a block

Block types are automatically registered when .tsx files are created in the blocks folder.

It’s expected that in each block file, you’ll have two export statements — one containing metadata and configuration for the block, and a component export created using defineBlock.

import { defineBlock } from "eddev/blocks"
 
export const meta: BlockMeta = {
  title: "Hello World",
  tags: ["root"]
}
 
export default defineBlock("content/hello-world", (props) => {
  return <div>Hello!</div>
})

defineBlock

Functionally, the defineBlock function doesn’t actually do anything: it just returns the function component parameter as-is. However, by specifying the name of the file in the first parameter (eg. content/hello-world), the type of props will be automatically inferred, since block props are the result of GraphQL queries.

This works, because of the pregenerated BlockProps type, which you can find in types.blocks.ts in your project.

Block Meta

Exporting the meta object, typed with the global BlockMeta type, provides hints to the eddev compiler and runtime, as well as to the Gutenberg editor.

Basic Properties

• title: string — The title of this block, shown in the editor.
• description: string — A description for this block, shown in the editor, when the block is selected.
• category: "text" | "media" | "design" | "widgets" | "theme" | "embed" | "layouts" — The category that this block will appear under, when an author is browsing the catalog of available blocks.
• icon: BlockIcon — Icon name to use for the block, in the editor. See the TypeScript type for the full list.
• keywords: string[] — Optional keywords, to assist with searching. Great for aliasing (eg. carousel and slider)

Block Tags

Since different blocks have different contexts, and are sometimes specific to certain page templates, post types, or sections of a page — it can be helpful to give these contexts some kind of nickname. This is where tags come in. Note that this is not a WordPress thing, but rather something specific to the eddev stack.

We typically use a couple of tags by default:

• inline for basic WYSIWYG blocks, like core headings/paragraphs/lists
• root for blocks that can be added at a top level for a page

For a hypothetical content-heavy site, with homepages, landing pages, subpages, and a blog, you might have a set of tags like:

• homepage-root — blocks that can only be added to the homepage
• landing-root — full-bleed blocks that can be added the root of a landing page
• subpage-root — blocks that work within the subpage grid (eg, 9 cols on desktop, 12 cols on mobile)
• article-root — blocks that can be used on an article page

We might also have additional tags for nested blocks, like a button tag that can be attached to a ‘Button Link’ block, as well as an ‘Add to Cart’ button block.

These tags will be referenced:

• In the allowedBlocks prop of InnerBlocks
• In the rootBlocks parameter when configuring the editor for a template or post type

Block Flags

Flags (not to be confused with Tags) allow you to set arbitrary key/values, which can be consumed by other parts of your frontend/editor code.

You set flags by passing an object, with arbitrary key/values, like so:

export const meta: BlockMeta = {
  title: "My Block",
  flags: {
    myFlag: true,
    somethingElse: "green"
  }
}

Then, when using InnerBlocks or ContentBlocks, you can use the flags in wrapBlock and spacer props — or inside your editor config — to intelligently wrap, style or filter blocks based on these values, rather than by name.

Use cases for this system:

• Applying class names to the wrapper element in the editor
• Deciding which blocks to wrap in animation components on the frontend, and which to exclude.
• Deciding which blocks to wrap in layout classes in a page template