Use Code Components

Use a Code Component when a reusable React implementation is clearer than a visual node tree but still needs to participate in Misaki Studio's typed properties, states, events, test cases, Preview, instances, and export pipeline.

Coverage: UI + MCP for source, contract, instances, and Preview. MCP has additional breakpoint and animatable-property workflows.

Choose Code or visual authoring

Use a Code Component for a renderable React unit that needs handwritten behavior, an existing code-based implementation, or a library pattern that does not map cleanly to editable nodes.

Use a visual Component when designers should manipulate its internal hierarchy and styles on the canvas. Use a Script for a callable helper or shared non-rendering function.

Code Components live under components/code/. Create them with Create Code Component or create-code-component; moving an ordinary Component into that structural folder is not a valid conversion path.

Define the contract first

1. Create the Code Component and open Logic.

2. Declare the properties, states, events, validators, variants, children, and test cases its source needs.

3. Add animatable properties only for numeric or color values that a timeline will push at frame rate.

4. Switch to Code and implement the current contract.

5. Preview representative test cases and place the Code Component in a visual parent.

Declared properties arrive as one object under props.properties, not directly on props. Other data-structure groups arrive as sibling capabilities such as states, content/data, API/storage, validation, timelines, and children. Read the current generated/starter contract before assuming exact field names.

Update source without breaking instances

Replace source in place instead of deleting and recreating the file. Keeping the file UUID preserves its declarations and every instance that references it.

The update path accepts the full source and checks compilation. It does not patch one fragment. Preserve code the task does not intend to replace, and review the complete diff before updating.

Ask an agent

In the Website project, inspect <Code Component reference>, its data structure, current full source, test cases, instances, and generated wrapper. Change only <bounded source behavior> while preserving the file UUID and public contract. If the contract must change, propose that change first and list affected instances. Replace the full source in place, report compilation output, preview <test cases>, inspect the authored source and generated wrapper, and stop. Do not delete/recreate the file or add a dependency without approval.

create-code-component creates a source-backed Component and update-code-component replaces its full source. Shared data-structure and Preview tools operate on the same file. Code-component debugging can pause, inspect frames, and resume supported breakpoints through MCP.

Animatable properties

Code Component animatable properties accept only number and color. A timeline writes them to the mounted host at frame rate, avoiding a normal React render per frame. Source can observe them through the provided animated interface or inherited CSS custom properties.

The Code Component's own file does not expose a visual Animate panel, so authoring its own timeline is currently MCP-only. A parent Page or visual Component can animate an instance from its own timeline UI.

Verify the result

• compile the full source and show any line/column error;

• read the declared contract and compare it with every source access;

• preview default and representative test cases;

• test emitted events, children, state, and data mounts;

• inspect the parent instance configuration;

• inspect authored source and generated wrapper through export-code;

• build the intended consumer with its real dependencies.

An import can fail because a dependency cannot be resolved or fetched; a silent network failure during a quick source check is not proof that the consumer contains that package.

Undo and side effects

Source and data-structure declarations are persisted content and use the file's shared history. Because an update replaces the complete source, verify the current content immediately before and after one undo.

Installing a package, changing a consumer application, or publishing output is external to that history.

Current limits

• There is no internal visual element tree to edit.

• Source must default-export the supported React Component shape.

• Only Code Components declare the frame-rate animatable-property structure.

• A compiling source file can still fail in a consumer because of dependencies, styles, framework assumptions, or runtime behavior.