Create a custom block

From an empty folder to a block in a live portal: scaffold, build with the playground, declare settings, deploy, and place it in the Portal Builder.

A custom block is a small web app that the end-customer portal shows next to its built-in blocks. Your team owns the code and the release; the portal owns login, theme and language and hands them to your block through @epilot/spark-sdk. Admins place the block with the Portal Builder and set it up per page, without a deploy.

This page takes you through the whole journey. Tick things off as you go: your progress stays in this browser, so you can come back tomorrow and pick up where you left off.

Prepare

You need Node.js 20 or newer and an epilot org to deploy to. Start with a dev or staging org; production comes last.

Before writing code, find out which entity holds your data in that portal. The same idea can live in different places: "requests" are tickets in one setup and opportunitys in another. Ask the portal's owner, or check the entity schemas in the org, so you don't build against the wrong one.

Create the project

npm create @epilot/spark-block offene-anfragen -- --title "Offene Anfragen"
cd offene-anfragen
npm install

The folder name becomes the package name; --title is the name admins see in the Portal Builder (you can change it later in spark-block.json).

FileWhat it's for
spark-block.jsonName, description, positions and the settings admins fill in
src/use-block.tsConnects to the portal once and gives you session, settings, entityIds and lang
src/app.tsxYour block. Starts with the connecting, no-portal and ready states
AGENTS.md, .mcp.jsonRules and the Spark MCP server for AI agents, already set up
spark-block.deploy.jsonWritten by the first deploy: app and component IDs per env and org

Building with an AI agent? Open the folder in Claude Code, Cursor or Codex. AGENTS.md, the spark skill and the Spark MCP server are already in place, so the agent knows the components, tokens and block rules from the first prompt. Describe what the block should show, and keep the playground open to review what it builds.

Run it in the playground

npm run dev

This opens the playground on http://localhost:4400. It stands in for the portal: it embeds your block (served on port 4401), answers the SDK handshake, and shows the settings form from spark-block.json.

  • de / en, light / dark, desktop / mobile switch what the portal would send. Your block must follow all of them live.
  • Block settings is the same form admins get. Change a value and watch the block update without a reload (onSettingsChange).
  • Bridge messages logs every message between block and portal. The first one is spark-bridge:init; if it's missing, the block never connected.
  • Page context sets the entityIds a detail page would pass, for example a contract ID.

The playground has no logged-in customer, so data calls return nothing. That is on purpose: the Portal Builder preview has no customer either (it answers 403). Show sample data or a neutral state there, never an error.

Describe the block

spark-block.json is the block's contract with the Portal Builder. It holds the name and description (German is required, English recommended), where the block may sit (main, footer_inline, footer_left_absolute, footer_right_absolute), and its settings: the fields an admin fills in for each placed block.

Try it below. Edit the JSON or add a field with the buttons: the form on the right is what the admin sees, and getSettings() shows what your block receives. It runs the same validation as npm run validate and the app API.

Add a field:

spark-block.json

Valid

Same check as npm run validate and the app API.

Portal Builder form

Leer lassen, um den Button auszublenden.

What getSettings() returns

{
  "heading": {
    "de": "Offene Anfragen",
    "en": "Open requests"
  },
  "limit": 5
}
TypeAdmin seesYour block gets
texta text input (maxLength)string
translated_textinputs for DE and EN{ de, en? }
numbera number input (min, max, step)number
booleana switchboolean
selecta dropdown of your optionsthe option's value
entity_schemathe org's schemas, or only alloweda schema slug, like ticket
pagethe portal's pagesa page slug, like requests
journeythe org's journeysa journey ID
color_tokenSpark color tokensaccent, success, blue, …

Rules worth knowing:

  • Settings are never secret. They reach the customer's browser, so the types secret, password and api_key, and fields marked sensitive, are rejected. Keys belong in the app installation or an integration, used server-side through executeUseCase.
  • Keys are your API. Renaming a key loses the value admins saved under the old one. Add a new key instead, and raise settings.version when the meaning of a field changes.
  • Up to 30 fields. Keys start with a lowercase letter and use letters, digits and _.
npm run validate

Build the block

useBlock() from the template gives you everything the portal sent:

import { t, useBlock } from './use-block'

const block = useBlock()
if (block.status !== 'ready') return null

const { settings, entityIds, lang } = block
const limit = typeof settings.limit === 'number' ? settings.limit : 5
const heading = t(settings.heading as { de: string; en?: string }, lang)

Outside the template, the same comes straight from the SDK:

import { getSettings, onSettingsChange } from '@epilot/spark-sdk'

const settings = getSettings<{ limit?: number }>()
onSettingsChange((next) => render(next))
  • Any setting can be missing: an admin may never have opened the form, or the block was placed before you added the field. Fall back in code.
  • Data comes through the SDK (entities, use cases). The portal holds the customer's login and only returns what that customer may see. Render loading, empty and error states.
  • Dialogs go through openDialog so they cover the page, not just your iframe. Toasts through toast.
  • Language: every string, aria-labels included, in de and en, picked by lang (localization).
  • Look like the portal: one Card, Tailwind utilities and Spark tokens only, no outer margin or padding.

The Build a block recipe walks through a complete, realistic block step by step.

Check it like a guest

Your block is a guest on someone else's page. Before deploying, run the three block tests in the playground:

  • Seam test. Next to other blocks, nothing gives away the iframe: no double spacing, no scrollbar (the template reports its height), no color that isn't the tenant's.
  • Whitelabel test. Switch to dark. Everything follows; anything that stays put is reading a literal color instead of a token.
  • Guest-manners test. Open http://localhost:4401 directly (no portal) and the block shows its friendly no-portal note. In the playground (no customer) it shows sample data or a neutral state.
npm run build

Deploy

EPILOT_TOKEN=<access token for the target org> npm run deploy -- --env dev

--env is dev, staging or prod; the org comes from the token. The deploy builds the block, then:

  1. creates the app on the first run (later runs reuse it),
  2. creates the version from package.json if it doesn't exist yet,
  3. uploads dist/ and waits until the CDN serves it,
  4. registers the CUSTOM_PORTAL_BLOCK component with your manifest and settings,
  5. installs the app in the org, or moves the installation to this version.

The IDs it created land in spark-block.deploy.json. Commit that file, so the next deploy (yours or a teammate's) updates the same app instead of creating a second one.

Place it in a portal

In the Portal Builder, open a page, add a block and pick yours under Custom Blocks. The settings form from your manifest appears in the property panel; defaults are filled in when you add the block. Publish the portal, then open the page as a logged-in customer: that's the first time your block sees real data.

Custom blocks run on pages behind the login only, because every data call needs a customer. The Portal Builder preview has no customer, so your block shows its sample or neutral state there.

Ship an update

Versions are immutable once public, so every release gets a new number:

  1. raise version in package.json (0.1.0 → 0.2.0),
  2. run the deploy again with the same --env,
  3. commit the updated spark-block.deploy.json.

The installation moves to the new version, and new placements use it.

Known gap: a block that is already on a page keeps the version it was added with. Until that's fixed, remove the block and add it again after an update. Its settings reset to the defaults, so note them first.

Troubleshooting

You seeDo this
No matching version found for @epilot/spark-… right after a releasenpm cached the old answer: npm install --prefer-online
spark-block.json has problems: description …Replace the template's placeholder with a real German sentence
Version 0.1.0 is public and cannot changeRaise version in package.json
No access tokenSet EPILOT_TOKEN for the org, or pass --token
The block says it runs inside a portalYou opened it directly; use npm run dev
403 on data calls in the Portal BuilderExpected: the preview has no customer. Check as a logged-in customer
The iframe scrolls or cuts off contentReport height from the block root (the template does); don't set a fixed height

On this page