imba-dev

Imba Language Guide

Source code. You can always look at the imba source code (in node_modules/imba or the linked imba package) for deeper investigation. The compiler lives in src/compiler/, the runtime in src/imba/.

Imba is a programming language that compiles to JavaScript. It has a dedicated syntax for building web UIs with tags (components), inline CSS, events, and a memoized DOM renderer. Official docs: https://imba.io/

For OP framework questions, use the op-dev skill instead.

Common Gotchas

These are the mistakes AI assistants make most often with Imba:

| style="bg:red" or style="background:..." | [bg:red] or css bg:red | Never use raw style attributes — use Imba's [...] inline syntax or css blocks | | css .on:l:16px | css x:0px .on:16px | Can't set a different PROPERTY in a class modifier — modifiers change the VALUE of the same property. | | css > div x:0px .on:16px (parent has .on) | css > div x:0px ..on:16px | .on: checks the element ITSELF for the class. ..on: checks ANCESTORS. Use .. when the flag is on a parent. Similarly &.on: explicitly matches the element itself |

Predicate Names and Trailing ?

Trailing ? is not a general boolean-method convention in Imba. Only accessor declarations should end with ?:

get media-emphasis?
	# property-style predicate, no args

set media-emphasis? value
	# setter for that property

Regular methods, including predicates that take arguments or a block, must not end with ?:

def has-media-emphasis block
	# ok

def media-emphasis? block
	# warns: Only getters/setters should end with ?

For predicate helpers, prefer names like is-ready, has-media-emphasis, or should-render-media; use get something? only when the API is property-like and needs no parameters.

Implicit Self & Global Identifiers

Imba uses implicit self for lowercase identifiers inside classes/tags. A bare someFunc(x) compiles to this.someFunc(x), not a global call. Only a specific set of identifiers are pre-registered as globals:

window, document, exports, console, process, parseInt, parseFloat, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, globalThis, isNaN, isFinite, __dirname, __filename, __realname, __pure__

For anything else (e.g., queueMicrotask, fetch, structuredClone, crypto, URL, Blob, AbortController, performance), use global. prefix:

global.queueMicrotask(do reflow!)
let resp = await global.fetch(url)
let id = global.crypto.randomUUID!

Passing methods as callbacks: Like in JS, passing a method reference to a callback (setTimeout(method)) loses this. Either wrap in do: setTimeout(do method!), or use the @bound decorator on the method definition.

Language Basics

Booleans

yes and no instead of true and false. Both compile to JS true/false. true/false work but are non-idiomatic.

Strings

• Single-quoted: 'no interpolation'
• Double-quoted: "with {expr} interpolation"
• Triple single: '''raw multiline, no interpolation'''
• Triple double: """multiline with interpolation, use \{ and \} to escape braces"""
• Tagged templates use backticks and {expr} interpolation; the tag receives first, ...rest, where first is the string-parts array and rest holds the rich interpolated values.

Optional Chaining

.. instead of ?.: obj..prop..method!

Operators

• == compiles to JS == (loose equality) — passes through directly
• != compiles to JS != (loose inequality) — passes through directly
• === and !== exist and compile directly to JS strict equality
• is compiles to is$(a, b) helper: a === b || b?.[matcher]?.(a) — strict equality plus custom matcher protocol. NOT the same as ==
• isnt compiles to !is$(a, b) — NOT the same as !=
• isa for instanceof (plus string type checks and Symbol.hasInstance): item isa Array
• !isa for negated: item !isa Array

Functions

def greet name
	"Hello {name}"

# Anonymous (inline or block)
let fn = do(x) x * 2

# Ampersand placeholder places a following block in a non-final argument slot
setTimeout(&, 500) do
	refresh!

# No-arg calls
save!          # same as save()

# Implicit return (last expression)
def double x
	x * 2

# Async (automatic when body uses await)
def fetch-data
	let res = await global.fetch("/api")
	await res.json!

Type Annotations

let count\number = 0
def greet name\string
	"Hello {name}"
def get-count\number
	count

Destructuring

Same as JS: let {a, b} = obj, let [x, y] = arr

Named Parameters

Named params implicitly create an object:

func(a: 1, b: 2)    # same as func({a: 1, b: 2})

Import / Export

Standard ES modules: import X from 'y', export def, export class, export default.

Import file contents as string: import text from './file.md?text'

Comments

# single line and ### multi-line block ###

Getters, Setters, Private

class Foo
	#count = 0          # private field
	get count
		#count
	set count value
		#count = value

Control Flow

Conditionals

if condition
	doA!
elif other
	doB!
else
	doC!

# unless = negated if
unless valid
	return

# Postfix
return if invalid
show! unless hidden

Ternary

condition ? valueA : valueB

Loops

for item in array
	process(item)

for item, index in array
	L index, item

for own key, value of object    # own properties only (NOTE: opposite of JS — in=arrays, of=objects)
	L key, value

while condition
	step!

for is an expression — it returns an array:

let doubled = for num in [1,2,3]
	num * 2

Conditional Assignment

=? only assigns if value changed, returns whether it changed:

if hidden =? yes
	animate!

Nullish Coalescing

??, ??=, ||=, &&= — same as JS.

Rescue (inline try/catch)

rescue expr wraps the right-hand expression in a try/catch and returns the thrown error instead of the result if it throws:

let res = rescue risky-call!
if res isa Error
	# handle/assert the failure

Compiles to (()=>{ try { return expr } catch(e) { return e } })(). Idiomatic for tests asserting that something throws (let err = rescue tree.add({as: Bad}) then assert err isa Error) and for tolerating expected failures without a try block. Note the success value and the error share one variable — only use it where isa Error (or similar) can distinguish them.

Template Control Flow

Inside <self>, use if and for directly:

<self>
	if showHeader
		<header> "Hello"
	for item in items
		<div> item.name

Classes

class Animal
	name
	sound = "..."

	def speak
		L "{name} says {sound}"

class Dog < Animal             # inheritance with <
	sound = "Woof"

global class MyService         # global = no import needed

extend class Dog               # reopen/extend existing class (no <)
	def fetch
		L "{name} fetches!"

extend class / extend tag limitations:

• You cannot override static def methods via extend class. The original static method will always be called. If you need to run init logic from an addon/extension, put it in a static def init on your own class instead.
• You cannot declare plain fields with default values in extend class or extend tag. Declarations like field = value or #field = value will not work. OP field declarations (field @string, field @int, etc.) ARE allowed. For plain fields, initialize them lazily in a method instead (e.g., #field ??= new Set in the method that uses it).

Static Members

class Config
	static version = "1.0"
	static def create
		new self

Mixins

isa MixinName in a class body applies a mixin (framework pattern):

tag my-app
	isa SomeMixin

Key Decorators

• @lazy — lazy evaluation, computed once on first access
• @bound — auto-bind method to instance
• @thenable — makes a method produce a thenable (awaitable) object
• @computed — memoized reactive getter
• @observable — reactive property
• @autorun — auto-running reaction

Declare

declare def method — type-only declaration, no implementation generated.

Deeper Topics

• Philosophy & Idioms — Native Imba patterns, ownership, state, CSS, and JS interop habits
• Tags & Components — Component system, lifecycle, props, slots, flags, rendering
• CSS System — Property shorthands, colors, modifiers, breakpoints
• Events — Event handlers, modifiers, touch/intersect/resize/hotkey
• Interop & Runtime — Scheduler, reactivity, storage, router, conditional compilation

External Docs

• Official documentation: https://imba.io/
• GitHub: https://github.com/imba/imba