Gea Framework

Gea Framework

Gea is a lightweight, reactive JavaScript UI framework built on the principle that JS code should be simple and understandable. It compiles JSX into efficient DOM operations at build time via a Vite plugin, uses proxy-based stores for state management, and employs event delegation for all user interactions. There is no virtual DOM — the Vite plugin analyzes your JSX templates and generates surgical DOM patches that update only the elements that depend on changed state.

Gea introduces no new programming concepts. There are no signals, no hooks, no dependency arrays, and no framework-specific primitives. Stores are classes with state and methods. Components are classes with a template() method or plain functions. Computed values are getters. The compile-time Vite plugin is the only "magic" — it analyzes ordinary JavaScript and wires up reactivity invisibly, so you write regular OOP/functional code that is fully reactive under the hood.

Read reference.md in this skill directory for the full API surface and detailed examples.

Core Concepts

Stores

A Store holds shared application state. Extend the Store class, declare reactive properties as class fields, and add methods that mutate them. The store instance is wrapped in a deep Proxy that tracks every property change and batches notifications via queueMicrotask.

import { Store } from '@geajs/core'

class CounterStore extends Store {
  count = 0

  increment() {
    this.count++
  }
  decrement() {
    this.count--
  }
}

export default new CounterStore()

Key rules:

• Always export a singleton instance (export default new MyStore()), not the class.
• Mutate properties directly — this.count++ triggers reactivity automatically.
• Use getters for derived/computed values — they re-evaluate on each access.
• Array mutations (push, pop, splice, sort, reverse, shift, unshift) are intercepted and produce fine-grained change events.
• Replacing an array with a superset (same prefix + new items) is detected as an efficient append operation.

Components

Gea has two component styles. Both compile to the same internal representation.

Class Components

Extend Component and implement a template(props) method that returns JSX. Class components can hold their own reactive properties — use them when you need local, transient UI state.

import { Component } from '@geajs/core'

export default class Counter extends Component {
  count = 0

  increment() { this.count++ }
  decrement() { this.count-- }

  template() {
    return (
      <div class="counter">
        <span>{this.count}</span>
        <button click={this.increment}>+</button>
        <button click={this.decrement}>-</button>
      </div>
    )
  }
}

Event handlers accept both method references (click={this.increment}) and arrow functions (click={() => this.increment()}). Use method references for simple forwarding; use arrow functions when passing arguments or composing logic.

Use class components when you need local component state or lifecycle hooks.

Function Components

Export a default function that receives props and returns JSX. The Vite plugin converts it to a class component internally.

export default function Greeting({ name }) {
  return <h1>Hello, {name}!</h1>
}

Use function components for stateless, presentational UI.

Props and Data Flow

Props follow JavaScript's native value semantics:

• Objects and arrays passed as props are the parent's reactive proxy. The child can mutate them directly, and both parent and child DOM update — two-way binding with zero ceremony.
• Primitives are copies. Reassigning a primitive prop in the child updates only the child's DOM — the parent is unaffected.

No emit, no v-model, no callback props needed for object/array mutations. Deep nesting works the same way — as long as the same reference is passed down, reactivity propagates across the entire tree.

Component State vs. Stores

A class component can have both local state and read from external stores:

export default class TodoItem extends Component {
  editing = false
  editText = ''

  template({ todo, onToggle, onRemove }) {
    const { editing, editText } = this
    return (
      <li class={`todo-item ${editing ? 'editing' : ''}`}>
        <span dblclick={this.startEditing}>{todo.text}</span>
        {/* ... */}
      </li>
    )
  }
}

Multiple Stores

Split state into domain-specific stores. Each store is an independent singleton.

flight-store.ts    → step, boardingPass
options-store.ts   → luggage, seat, meal
payment-store.ts   → passengerName, cardNumber, paymentComplete

Stores can import and call each other:

class FlightStore extends Store {
  startOver(): void {
    this.step = 1
    optionsStore.reset()
    paymentStore.reset()
  }
}

A root component reads from all relevant stores and passes data down as props:

export default class App extends Component {
  template() {
    const { step } = flightStore
    const { luggage } = optionsStore
    return <div>{step === 1 && <OptionStep selectedId={luggage} onSelect={id => optionsStore.setLuggage(id)} />}</div>
  }
}

Router

Gea includes a built-in client-side router. The router is a Store that reactively tracks path, params, query, and hash. Define routes with setRoutes or createRouter.

Setup

Create a bare Router in router.ts. Keep this file free of view imports to avoid circular dependencies (views import router, so router.ts must not import views).

// src/router.ts
import { Router } from '@geajs/core'
export const router = new Router()

Set routes in App.tsx where both the router and view components are available:

// src/App.tsx
import { Component, Outlet } from '@geajs/core'
import { router } from './router'
import AppShell from './views/AppShell'
import Home from './views/Home'
import About from './views/About'
import UserProfile from './views/UserProfile'
import NotFound from './views/NotFound'

router.setRoutes({
  '/': {
    layout: AppShell,
    children: {
      '/': Home,
      '/about': About,
      '/users/:id': UserProfile,
    },
  },
  '*': NotFound,
})

export default class App extends Component {
  template() {
    return <Outlet />
  }
}

Layouts receive the resolved child as a page prop:

export default class AppShell extends Component {
  template({ page }: any) {
    return (
      <div class="app">
        <nav>
          <Link to="/" label="Home" />
          <Link to="/about" label="About" />
        </nav>
        <main>{page}</main>
      </div>
    )
  }
}

For simple apps without layouts/guards (no circular dependency risk), you can use createRouter directly in router.ts and render with <RouterView router={router} />:

import { createRouter } from '@geajs/core'
import Home from './views/Home'
import About from './views/About'

export const router = createRouter({
  '/': Home,
  '/about': About,
} as const)

import { Component, RouterView } from '@geajs/core'
import { router } from './router'

export default class App extends Component {
  template() {
    return <RouterView router={router} />
  }
}

Guards

Guards are synchronous functions on route groups that control access. A guard returns:

• true — proceed to the route
• string — redirect to that path
• Component — render it instead of the route

import authStore from './stores/auth-store'

const AuthGuard = () => {
  if (authStore.isAuthenticated) return true
  return '/login'
}

router.setRoutes({
  '/login': Login,
  '/': {
    layout: AppShell,
    guard: AuthGuard,
    children: {
      '/dashboard': Dashboard,
      '/settings': Settings,
    },
  },
})

Guards on nested groups stack parent → child. Guards are intentionally synchronous — they check store state, not async APIs. For async checks, use created() in the component.

Route Patterns

• Static: /about
• Named params: /users/:id — extracted as { id: '42' }
• Wildcard: * — matches any unmatched path
• Redirects: '/old': '/new' — string values trigger a redirect
• Lazy routes: '/admin': () => import('./views/Admin') — code-split route components

Link

Renders an <a> tag that navigates with history.pushState. Modifier keys (Cmd/Ctrl+click) open in a new tab. Active links receive data-active and an active class; pass exact to require an exact path match.

<Link to="/about" label="About" class="nav-link" />

Programmatic Navigation

import { router } from './router'

router.push('/about')         // pushState
router.navigate('/about')     // alias for push
router.replace('/login')      // replaceState
router.back()
router.forward()
router.go(-2)

Route Parameters

Function components receive matched params as props:

export default function UserProfile({ id }) {
  return <h1>User {id}</h1>
}

Class components receive them via created(props) and template(props). Route params are also available on router.params.

Active State

router.isActive('/dashboard')  // true if path starts with /dashboard
router.isExact('/dashboard')   // true only for exact match

matchRoute Utility

Use matchRoute for manual route matching:

import { matchRoute } from '@geajs/core'

const result = matchRoute('/users/:id', '/users/42')
// { path: '/users/42', pattern: '/users/:id', params: { id: '42' } }

RouterView

RouterView renders the current route. Use it with a router prop for createRouter setups, or with an inline routes array for quick prototypes:

// With createRouter (recommended)
<RouterView router={router} />

// With inline routes (uses the singleton router)
<RouterView routes={[
  { path: '/', component: Home },
  { path: '/about', component: About },
  { path: '/users/:id', component: UserProfile },
]} />

JSX Rules

Gea JSX differs from React JSX in several ways:

Both native-style (click, change) and React-style (onClick, onChange) event attribute names are supported. Native-style is preferred by convention.

Supported event attributes include mouse, keyboard, form, drag, touch, pointer, wheel, scroll, animation, and transition events: click, dblclick, input, change, submit, keydown, keyup, blur, focus, pointerdown, pointerup, pointermove, touchstart, touchmove, touchend, wheel, scroll, dragstart, dragend, dragover, dragleave, drop, animationstart, animationend, transitionstart, transitionend, and related variants.

With @geajs/mobile: tap, longTap, swipeRight, swipeUp, swipeLeft, swipeDown.