@boilerscript/custom-block-cli

Create, live-preview, and build portable Vue custom form blocks for BoilerScript.

Requirements

• Node.js 20.19 or newer
• pnpm, npm, or another package runner

pnpm dlx downloads the CLI into pnpm's temporary cache, so authors do not need the BoilerScript repository or a global CLI installation.

Quick start

pnpm dlx @boilerscript/custom-block-cli init my-block
cd my-block
pnpm dlx @boilerscript/custom-block-cli preview --open
pnpm dlx @boilerscript/custom-block-cli build

The generated starter previews and builds immediately without a local install. The preview hot-reloads changes to Vue components, TypeScript, styles, and local imported assets. It also includes editable field, modelValue, and formData fixtures and shows every output emitted through updateOutput or update:modelValue.

Run pnpm install when you want editor type support and the shorter local commands:

pnpm dev
pnpm build

pnpm dev opens the preview automatically. The preview mirrors BoilerScript's component API, but it is a trusted local development page rather than the packaged app's production sandbox. Always test the final .bsformblock inside BoilerScript before publishing a block.

The output is dist/my-block.bsformblock. Copy that one file into BoilerScript's custom-form-blocks directory and press Reload in the form builder.

Build an existing block

From inside its source folder:

pnpm dlx @boilerscript/custom-block-cli build

Or pass a source and output path:

pnpm dlx @boilerscript/custom-block-cli build /path/to/my-block \
  --out /path/to/custom-form-blocks/my-block.bsformblock

The source config.json needs an entry pointing to a Vue component:

{
  "id": "my-block",
  "name": "My block",
  "description": "Shown in the form builder.",
  "entry": "src/CustomBlock.vue",
  "packageVersion": "1.0.0",
  "defaultValue": null,
  "outputSchema": {
    "type": "number"
  },
  "fieldDefaults": {
    "label": "My block"
  }
}

The component receives field, modelValue, formData, and updateOutput. Calling updateOutput(jsonValue) or emitting update:modelValue updates the form field.

Describe structured output

When a block outputs an object, declare its shape with outputSchema. BoilerScript uses this metadata to suggest nested values in code variables and nested arrays in loops. Dynamic paths can still be entered manually, but a schema makes the editor much easier to use.

{
  "defaultValue": null,
  "outputSchema": {
    "type": "object",
    "properties": {
      "customer": {
        "type": "object",
        "properties": {
          "email": { "type": "string" }
        }
      },
      "lines": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "quantity": { "type": "integer" }
          }
        }
      }
    }
  }
}

Supported schema types are object, array, string, number, integer, boolean, and null. Object fields go in properties; array element shapes go in items. If outputSchema is omitted, BoilerScript tries to infer a shape from a non-null defaultValue.

Multiple Vue files, <script setup>, Composition API, TypeScript syntax, scoped CSS, SCSS, browser-compatible dependencies, and imported assets are supported. Vue is supplied by BoilerScript at runtime. Install any additional browser dependency inside the block project before importing it.

The CLI uses a fixed Vite configuration. It does not load source-project Vite config, .env, PostCSS plugins, package scripts, Node/Electron imports, remote imports, or source maps. Build only source projects you trust: preprocessors and installed dependencies are build-time code and the builder is not an operating-system sandbox.

Preview options

From inside a block project:

pnpm dlx @boilerscript/custom-block-cli preview --open

You can also preview another source folder or expose the development server on your network:

pnpm dlx @boilerscript/custom-block-cli preview /path/to/my-block \
  --host 0.0.0.0 --port 4173

Run preview --help for all options. dev is an alias for preview.