Flowbox-init and Frontend Harness Architecture

This page explains what the “flowbox-init” step actually wires in the frontend harness.

What “flowbox-init” means here

flowbox-init maps to:

npx flowbox-ui init

The command is implemented in sdk/config/flowbox-ui/cli/index.js (init()), and performs scaffold + dependency setup.

Harness architecture (levels)

Level 1: Scaffold and package baseline

• Copies sdk/config/flowbox-ui/templates/base/* into the worker frontend folder.
• Creates baseline package.json and vite.config.js.
• Installs toolkit runtime and build dependencies.

Level 2: Component entries

• npx flowbox-ui add <name> creates src/<name>/main.js and ConfigForm.svelte.
• Each component folder is one build entry.

Level 3: Dev harness runner

• npx flowbox-ui start <name> generates temporary dev assets:
  • .flowbox-dev/vite.config.js
  • index.html with __COMPONENT__ replacement
  • src/<name>/test/config.json when missing
• Dev harness simulates FlowMaker props and save-cycle behavior.

Level 4: Production packaging

• npm run build iterates src/*/ and builds an IIFE jsbundle per component.
• Runtime registration uses base64 of config/config.<name>.jsbundle.js.

[NOTE!lightbulb/LEVEL OWNERSHIP] Levels 1-3 are local developer ergonomics. Level 4 is the deployable artifact contract consumed by FlowMaker.

Important operational behavior

[WARNING!schedule/UPDATE OVERWRITES] flowbox-ui update rewrites template-managed files (vite.config.js, vite.config.dev.js, index*.html). Keep custom edits minimal or isolate them in component code.

[NOTE!lightbulb/ESM TOOLING] Toolkit package and generated frontend use ESM ("type": "module"). Keep config/custom scripts ESM-compatible.

Reference

• sdk/config/flowbox-ui/cli/index.js
• sdk/config/flowbox-ui/templates/base/package.json
• sdk/config/flowbox-ui/templates/dev/vite.config.dev.js