Custom Nodes

> Brickr now has two different extension paths: visual custom nodes in the dashboard and code-native custom nodes powered by the CLI and SDK.

If you need behavior that does not exist in Brickr's built-in node library, you can extend Brickr in two ways:

| Approach | Best for | Main tools | |----------|----------|------------| | Visual custom nodes | Reusable logic created inside Brickr's UI | Dashboard custom node builder | | Custom code nodes | TypeScript / JavaScript nodes authored locally | brickr CLI + @brickr/sdk |

This page is the bridge between those two systems. If you want the new local authoring flow, start with the Custom Code docs below.

The new custom code system

Brickr custom code nodes let you:

  • scaffold a local project with brickr init
  • define nodes in src/**/*.br.ts or src/**/*.br.js
  • describe pins with @brickr/sdk
  • test locally with brickr dev
  • publish to the workspace dev channel with brickr deploy dev
  • promote to production with brickr deploy prod
  • manage shared enums, structures, and secrets in brickr.config.ts

This is the recommended path when your node logic is real source code rather than a visual composition.

Start here for custom code

| Page | What it covers | |------|----------------| | Custom Code Overview | Architecture, lifecycle, and project structure | | Custom Code CLI | Commands for init, update, dev, deploy, status, secrets, and asset sync | | Custom Code SDK | defineCodeFunctionNode, pin builders, context, enums, structures, and secrets | | Custom Code Workflow | Recommended day-to-day authoring and deployment flow |

When visual custom nodes still make sense

The dashboard custom node builder is still useful when you want to package existing Brickr nodes into a reusable visual block without introducing a local repository or a code deployment flow.

Use the visual builder when:

  • the logic is mostly existing Brickr nodes wired together
  • non-developers need to maintain the node in the UI
  • you want to share a visual composition inside Brickr without a code package

Use custom code when:

  • you need real JavaScript or TypeScript
  • you want local tests before publishing
  • you want source control, review, and package management around your nodes
  • you want code-managed enums, structures, and secrets

Shared idea across both systems

Both paths ultimately produce Builder nodes with:

  • a name and description
  • typed inputs and outputs
  • category placement in the Builder
  • workspace scoping
  • reusable behavior across flows

If your goal is "build custom nodes in code", do not start in the old dashboard-only flow. Start in the Custom Code Overview and use the CLI + SDK workflow.

Best practices

  • Keep identities stable -- Whether visual or code-based, avoid renaming the underlying node identity without a good migration reason.
  • Document pin behavior -- Good names and pin descriptions matter more than implementation style.
  • Test in context -- Validate the node inside a real Builder flow, not only in isolation.
  • Prefer code-managed assets for code nodes -- Shared enums, structures, and secrets belong in brickr.config.ts.

Changing a shared custom node can affect every flow that uses it. Use the dev-first flow for code nodes and validate before promoting to production.

What's next?

| Topic | Description | |-------|-------------| | Custom Code Overview | Big-picture guide to the new local custom code system | | Custom Code CLI | Command reference for testing and deployment | | Custom Code SDK | API reference for node definitions and shared assets | | Type System | Broader type-system background for pins, enums, structures, and arrays |