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 installThe 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).
| File | What it's for |
|---|---|
spark-block.json | Name, description, positions and the settings admins fill in |
src/use-block.ts | Connects to the portal once and gives you session, settings, entityIds and lang |
src/app.tsx | Your block. Starts with the connecting, no-portal and ready states |
AGENTS.md, .mcp.json | Rules and the Spark MCP server for AI agents, already set up |
spark-block.deploy.json | Written 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 devThis 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
entityIdsa 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.
spark-block.json
Same check as npm run validate and the app API.
Portal Builder form
What getSettings() returns
{
"heading": {
"de": "Offene Anfragen",
"en": "Open requests"
},
"limit": 5
}| Type | Admin sees | Your block gets |
|---|---|---|
text | a text input (maxLength) | string |
translated_text | inputs for DE and EN | { de, en? } |
number | a number input (min, max, step) | number |
boolean | a switch | boolean |
select | a dropdown of your options | the option's value |
entity_schema | the org's schemas, or only allowed | a schema slug, like ticket |
page | the portal's pages | a page slug, like requests |
journey | the org's journeys | a journey ID |
color_token | Spark color tokens | accent, success, blue, … |
Rules worth knowing:
- Settings are never secret. They reach the customer's browser, so the
types
secret,passwordandapi_key, and fields markedsensitive, are rejected. Keys belong in the app installation or an integration, used server-side throughexecuteUseCase. - Keys are your API. Renaming a key loses the value admins saved under the
old one. Add a new key instead, and raise
settings.versionwhen the meaning of a field changes. - Up to 30 fields. Keys start with a lowercase letter and use letters,
digits and
_.
npm run validateBuild 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
openDialogso they cover the page, not just your iframe. Toasts throughtoast. - Language: every string,
aria-labels included, in de and en, picked bylang(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 buildDeploy
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:
- creates the app on the first run (later runs reuse it),
- creates the version from
package.jsonif it doesn't exist yet, - uploads
dist/and waits until the CDN serves it, - registers the
CUSTOM_PORTAL_BLOCKcomponent with your manifest and settings, - 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:
- raise
versioninpackage.json(0.1.0→0.2.0), - run the deploy again with the same
--env, - 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 see | Do this |
|---|---|
No matching version found for @epilot/spark-… right after a release | npm 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 change | Raise version in package.json |
No access token | Set EPILOT_TOKEN for the org, or pass --token |
| The block says it runs inside a portal | You opened it directly; use npm run dev |
403 on data calls in the Portal Builder | Expected: the preview has no customer. Check as a logged-in customer |
| The iframe scrolls or cuts off content | Report height from the block root (the template does); don't set a fixed height |