DEV Community

Amith Moorkoth
Amith Moorkoth

Posted on

Add Your Own Component to Bombie in 5 Edits

#react #tutorial #opensource #materialui

This is the third post in the Bombie series. The first post was an intro, the second covered the architecture. This one is a hands-on walkthrough: take a Material-UI component that isn't already in Bombie, and wire it up so it appears in the palette, drags onto the canvas, opens a property editor, and renders in the live preview.

The whole change is five small edits across the same five files for every new component. Once you've done one, the next one takes about ten minutes.

I'll use Rating as the running example. It's a single-leaf component (no children), it has a small but meaningful prop surface (value, max, precision, size, readOnly, disabled), and it's not already in the catalog.

Prerequisites

Clone and run Bombie locally:

git clone https://github.com/amith-moorkoth/bombie.git
cd bombie
cp .env.example .env
npm install
npm start
Enter fullscreen mode Exit fullscreen mode

You'll get the builder at http://localhost:8080/generate-component. Open src/Lib/ComponentGenerator/ — every file you're going to touch lives under there.

Edit 1: register the component in the catalog

The catalog is the source of truth for what Bombie knows about. It lives in two files:

  • Data/element-base.js — display name + tag
  • Data/elements.js — drag-and-drop type info

Add Rating to element-base.js:

// src/Lib/ComponentGenerator/Data/element-base.js
export const ELEMENT_BASE = {
  // …existing entries
  Rating: { tag: "Rating", displayName: "Rating" },
};
Enter fullscreen mode Exit fullscreen mode

And to elements.js:

// src/Lib/ComponentGenerator/Data/elements.js
export const ELEMENTS = {
  // …existing entries
  Rating: {
    type: "leaf",         // it's a leaf, no children
    accept: [],           // it doesn't accept any drops
  },
};
Enter fullscreen mode Exit fullscreen mode

type controls where this component can be dropped (most things accept "leaf"). accept is what this component allows as a child — empty for leaves like Rating, populated for containers like Box / Grid / Stack.

Edit 2: write the builder UI file

This is the only new file you'll create. It defines two things: the schema (what the property editor shows) and the render (what the canvas draws).

Create src/Lib/ComponentGenerator/Container/UI/Rating.js:

// src/Lib/ComponentGenerator/Container/UI/Rating.js
import Rating from "@mui/material/Rating";
import { makeLeafComponent } from "./Common/make-component";

export default makeLeafComponent({
  tag: "Rating",

  schema: {
    Appearance: {
      size: {
        type: "select",
        options: ["small", "medium", "large"],
        default: "medium",
      },
      max: {
        type: "number",
        default: 5,
        min: 1,
        max: 10,
      },
      precision: {
        type: "select",
        options: [0.5, 1],
        default: 1,
      },
    },
    State: {
      value: {
        type: "number",
        default: 3,
        min: 0,
      },
      readOnly: { type: "boolean", default: false },
      disabled: { type: "boolean", default: false },
    },
  },

  render: ({ props }) => <Rating {...props} />,

  // Optional defaults applied when the component is dropped on the canvas
  defaultProps: { value: 3, max: 5, precision: 1, size: "medium" },
});
Enter fullscreen mode Exit fullscreen mode

A few notes on what's happening here:

  • makeLeafComponent is a factory from UI/Common/make-component.js. It wraps the renderer with the builder chrome (selection outline, wrench button, delete button) and registers the schema so the property editor knows what controls to show.
  • Schema groups become sections in the property dialog. "Appearance" gets one card, "State" gets another. This is what makes the editor scannable instead of a wall of inputs.
  • Field types the editor knows about: string, number, boolean, select, color. Anything else falls through to a text input.
  • render receives the node's props (already merged with defaults) and returns plain JSX. No builder logic in this function — that's what the wrapper handles.

For container components (Box, Grid, Stack, Card, etc.) you'd use makeContainerComponent instead. It accepts the same schema / render shape but also wires up a <DropBox> around the children so things can be dropped inside.

Edit 3: register it in the renderer switch

The canvas uses a central registry to know which builder UI file handles which tag. Add Rating to it:

// src/Lib/ComponentGenerator/Container/element-render.js
import Rating from "./UI/Rating";
// …other imports

export const REGISTRY = {
  // …existing entries
  Rating,
};
Enter fullscreen mode Exit fullscreen mode

This is the registry the recursive renderer (element-recursion.js) consults for every node it walks. node.info.tag looks up its renderer here.

Edit 4: add an icon + put it in a palette category

The palette in the left sidebar groups components by category. Two small additions:

// src/Lib/ComponentGenerator/Elements/icon-map.js
import StarIcon from "@mui/icons-material/Star";
// …

export const ICON_MAP = {
  // …existing entries
  Rating: StarIcon,
};
Enter fullscreen mode Exit fullscreen mode 
// src/Lib/ComponentGenerator/Elements/index.js
export const CATEGORIES = {
  Layout:      [/* … */],
  "Form Elements":  ["TextField", "Select", /* …, */ "Rating"], // add here
  "Data Display":   [/* … */],
  Feedback:    [/* … */],
  Navigation:  [/* … */],
};
Enter fullscreen mode Exit fullscreen mode

Categories are just arrays of tags. Pick the one that makes sense — Rating is technically a form input but it's also a display element. I put it under "Form Elements" because it has a value and a readOnly mode, but "Data Display" is a defensible choice too.

Edit 5: teach the preview about it

The live preview has its own renderer (render-preview.js) that emits clean MUI JSX without builder chrome. It uses a switch keyed by tag — add a branch:

// src/Lib/ComponentGenerator/Preview/render-preview.js
import Rating from "@mui/material/Rating";
// …

const RENDERERS = {
  // …existing entries
  Rating: ({ node }) => <Rating {...node.props} />,
};
Enter fullscreen mode Exit fullscreen mode

That's it. The preview will now render Rating the same way the canvas does, minus the outline and wrench.

Testing your change

Hot-reload should pick everything up. Open the builder, find "Rating" in the Form Elements category, drag it onto the canvas. You should see five stars with the third one filled in (your defaultProps.value: 3).

Click the wrench. You should see the property dialog with two sections — "Appearance" with size / max / precision, and "State" with value / readOnly / disabled. Flip "readOnly" to true, change value to 4.5 (oh wait — precision is 1; set precision to 0.5 first, then 4.5 works).

Click Preview. The iframe shows your component without any builder chrome. Toggle Mobile / Tablet / Desktop — Rating doesn't have responsive breakpoints itself, but if you'd dropped it inside a Grid it would reflow correctly.

If something doesn't render: the most common culprit is forgetting Edit 3 (register in element-render.js) or Edit 5 (register in render-preview.js). One controls the canvas, the other controls the preview, and the symptoms are different — canvas-only failures mean a missing entry in element-render.js, preview-only failures mean a missing entry in render-preview.js.

What about container components?

For containers, two things change:

  1. Use makeContainerComponent instead of makeLeafComponent. It wraps a <DropBox> around the rendered children.
  2. In elements.js, set type: "container" and populate accept with the tags this container will receive (usually ["leaf", "container"] to allow nesting).

The render function for a container gets children it should render the canvas-rendered subtree into. Example skeleton:

makeContainerComponent({
  tag: "MyContainer",
  schema: { /* … */ },
  render: ({ props, children }) => (
    <MyContainer {...props}>{children}</MyContainer>
  ),
});
Enter fullscreen mode Exit fullscreen mode

children here is the already-rendered subtree (with builder chrome on the canvas, plain JSX in the preview).

A note on prop validation

Bombie doesn't enforce prop validation beyond what MUI itself does at runtime. If you put value: 99 on a Rating with max: 5, MUI will clamp it. The schema's min/max hints are advisory — the editor uses them for its number input UI, but the property dialog won't refuse to let you save an out-of-range value.

In practice this hasn't been a problem because the editor's controls (select dropdowns, numeric inputs with min/max) make it hard to enter nonsense in the first place. But if you're adding a component with strict prop constraints, document them in the schema using a description field — the property dialog will surface it as helper text.

Recap

For any new component, the five edits are:

  1. Catalog — Data/element-base.js + Data/elements.js
  2. Builder UI — one new file under Container/UI/
  3. Renderer registry — add to REGISTRY in element-render.js
  4. Palette — add icon to icon-map.js and tag to Elements/index.js
  5. Preview renderer — add a branch in render-preview.js

There's no central manifest file that needs to be regenerated, no build step that needs to run, no test that needs to pass before the new component shows up. Hot-reload picks everything up in seconds.

The whole architecture is built around making this addition cheap, because the practical value of Bombie scales with how many MUI components it knows about. PRs that add components are exactly the kind of contribution I want.

In the next post — last in this series — I'll cover the operational lessons: GitHub Pages SPA deep links, the CSP-per-mode setup, and why bombie-three.vercel.app ended up on Vercel even though the repo has a GitHub Pages workflow.

Links

Top comments (0)