Vibe Coding with AI

Best practices for building Constela applications with AI assistance

Why Constela Works Well with AI

Constela is uniquely suited for AI-assisted development. Here's why:

Feature	Benefit for AI
JSON format	LLMs excel at generating structured JSON
Schema validation	Compiler catches errors, enabling self-correction
Detailed error messages	AI can read errors and fix its own mistakes
Limited expression types	Smaller vocabulary = higher accuracy
Declarative patterns	Predictable, learnable structures

Note

When AI generates invalid Constela code, the compiler provides specific error messages that help the AI understand and fix issues—often without human intervention.

Setting Up Your AI Environment

CLAUDE.md Configuration

Create a CLAUDE.md file in your project root with Constela-specific context:

markdown

# Constela Project

## Expression Types
- `lit` - Literal values: `{ "expr": "lit", "value": X }`
- `state` - State reference: `{ "expr": "state", "name": "fieldName" }`
- `var` - Variable/event: `{ "expr": "var", "name": "item", "path": "prop" }`
- `param` - Component param: `{ "expr": "param", "name": "title" }`
- `bin` - Binary operation: `{ "expr": "bin", "op": "+", "left": ..., "right": ... }`
- `not` - Negation: `{ "expr": "not", "operand": ... }`
- `cond` - Conditional value: `{ "expr": "cond", "if": ..., "then": ..., "else": ... }`
- `get` - Property access: `{ "expr": "get", "base": ..., "path": "prop" }`

## State Types
- `number`, `string`, `boolean`, `list`, `object`

## Update Operations
- Number: `increment`, `decrement`
- Boolean: `toggle`
- List: `push`, `pop`, `remove`, `replaceAt`, `insertAt`, `splice`
- Object: `merge`

## Common Mistakes
- All values must be wrapped in expressions (use `{ "expr": "lit", "value": X }`)
- Event handlers: `{ "event": "click", "action": "actionName" }`
- Text nodes require expressions: `{ "kind": "text", "value": { "expr": "lit", "value": "Hello" } }`

Reference Files

Point your AI to these key resources:

Existing code - Working examples in your src/ directory
Documentation - This site's Docs section
Reference - This site's Reference section

Tip

Providing 2-3 working examples from your own codebase is more effective than extensive documentation. AI learns patterns better from concrete examples.

Effective Prompt Patterns

Few-Shot Learning

Always start by showing the AI a working example:

text

Here's a working Constela counter component:

{
  "state": {
    "count": { "type": "number", "initial": 0 }
  },
  "actions": [
    {
      "name": "increment",
      "steps": [
        { "do": "update", "target": "count", "operation": "increment" }
      ]
    }
  ],
  "view": {
    "kind": "element",
    "tag": "button",
    "props": { "onClick": { "event": "click", "action": "increment" } },
    "children": [
      { "kind": "text", "value": { "expr": "state", "name": "count" } }
    ]
  }
}

Now create a similar component that [your requirement]...

Iterative Error Correction

When the AI generates invalid code:

text

The compiler returned this error:

[ERROR] Invalid operation 'toggle' for state type 'number'.
  Expected: number operation (increment, decrement)
  At: actions[0].steps[0]

Please fix the code based on this error message.

Important

Copy the full compiler error message. Constela's errors include context that helps AI understand exactly what went wrong.

Task-Specific Templates

For new components:

text

Create a Constela component for [description].

State needed:
- [state fields]

User interactions:
- [events and behaviors]

Follow the patterns in the existing components in src/pages/.

For modifying existing code:

text

Here's the current Constela code:

[paste code]

Modify it to [change description].

Keep the existing structure and only change what's necessary.

Common Pitfalls and Solutions

Pitfall 1: Missing Expression Wrappers

AI often forgets to wrap values in expressions, especially when coming from React/Vue habits.

Wrong	Correct
`"value": "Hello"`	`"value": { "expr": "lit", "value": "Hello" }`
`"value": 42`	`"value": { "expr": "lit", "value": 42 }`
`"value": true`	`"value": { "expr": "lit", "value": true }`

Pitfall 2: Incorrect Event Handler Format

Wrong	Correct
`"onClick": "handleClick"`	`"onClick": { "event": "click", "action": "handleClick" }`
`"onClick": { "action": "handleClick" }`	`"onClick": { "event": "click", "action": "handleClick" }`

Pitfall 3: Confusing state and var

Context	Use
Accessing global state	`{ "expr": "state", "name": "count" }`
Inside `each` loop	`{ "expr": "var", "name": "item" }`
Accessing event data	`{ "expr": "var", "name": "event", "path": "target.value" }`
Accessing action parameters	`{ "expr": "var", "name": "paramName" }`

Note

state is for top-level application state. var is for scoped variables: loop items, event objects, and action parameters.

Pitfall 4: Confusing if Node and cond Expression

Purpose	Use
Conditionally render elements	`if` node
Compute a value conditionally	`cond` expression

if node - Controls what gets rendered:

json

{
  "kind": "if",
  "condition": { "expr": "state", "name": "isLoggedIn" },
  "then": { "kind": "text", "value": { "expr": "lit", "value": "Welcome!" } },
  "else": { "kind": "text", "value": { "expr": "lit", "value": "Please log in" } }
}

cond expression - Returns a value:

json

{
  "kind": "text",
  "value": {
    "expr": "cond",
    "if": { "expr": "state", "name": "isLoggedIn" },
    "then": { "expr": "lit", "value": "Welcome!" },
    "else": { "expr": "lit", "value": "Please log in" }
  }
}

Pitfall 5: Wrong Operation for State Type

State Type	Valid Operations
`number`	`increment`, `decrement`
`boolean`	`toggle`
`list`	`push`, `pop`, `remove`, `replaceAt`, `insertAt`, `splice`
`object`	`merge`

Recommended Workflow

text

┌─────────────────────────────────────────┐
│  1. Describe requirement to AI          │
│     (Include working examples)          │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│  2. AI generates Constela JSON          │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│  3. Run: constela dev                   │
└──────────────────┬──────────────────────┘
                   ▼
         ┌────────────────────┐
         │  Compiler errors?  │
         └─────────┬──────────┘
           Yes │         │ No
               ▼         ▼
┌──────────────────┐  ┌──────────────────┐
│ Feed errors to   │  │ 4. Check in      │
│ AI, go to step 2 │  │    browser       │
└──────────────────┘  └────────┬─────────┘
                               ▼
                    ┌────────────────────┐
                    │  Behaves correctly?│
                    └─────────┬──────────┘
                      No │         │ Yes
                         ▼         ▼
          ┌──────────────────┐  ┌──────────┐
          │ Describe issue   │  │ 5. Done! │
          │ to AI, step 2    │  └──────────┘
          └──────────────────┘

Tip

The compile → error → fix cycle is usually 2-3 iterations. Constela's specific error messages make each iteration quick.

Quick Reference

Expression Cheat Sheet

Type	Syntax	Example
Literal	`{ "expr": "lit", "value": X }`	`{ "expr": "lit", "value": "Hello" }`
State	`{ "expr": "state", "name": "N" }`	`{ "expr": "state", "name": "count" }`
Variable	`{ "expr": "var", "name": "N" }`	`{ "expr": "var", "name": "item" }`
Var + Path	`{ "expr": "var", "name": "N", "path": "P" }`	`{ "expr": "var", "name": "event", "path": "target.value" }`
Binary	`{ "expr": "bin", "op": "O", "left": L, "right": R }`	`{ "expr": "bin", "op": "+", "left": ..., "right": ... }`
Conditional	`{ "expr": "cond", "if": C, "then": T, "else": E }`	See examples above
Get	`{ "expr": "get", "base": B, "path": "P" }`	`{ "expr": "get", "base": { "expr": "var", "name": "item" }, "path": "name" }`

Action Step Cheat Sheet

Step	Syntax	Description
Set	`{ "do": "set", "target": "T", "value": V }`	Replace state value
Update	`{ "do": "update", "target": "T", "operation": "O" }`	Modify state
Update + Value	`{ "do": "update", "target": "T", "operation": "O", "value": V }`	Modify with value

View Node Cheat Sheet

Node	Syntax	Use
Element	`{ "kind": "element", "tag": "div", "children": [...] }`	HTML elements
Text	`{ "kind": "text", "value": EXPR }`	Text content
If	`{ "kind": "if", "condition": C, "then": T, "else": E }`	Conditional rendering
Each	`{ "kind": "each", "items": I, "as": "item", "body": B }`	List iteration
Component	`{ "kind": "component", "name": "N", "props": {...} }`	Reusable components

Event Handler Format

json

{
  "props": {
    "onClick": { "event": "click", "action": "actionName" },
    "onInput": { "event": "input", "action": "actionName" },
    "onSubmit": { "event": "submit", "action": "actionName" }
  }
}

Next Steps

Review State & Expressions for detailed expression documentation
See Actions & Events for action step reference
Check the Reference for complete API documentation