@geajs/core

中文文档
1.5.1发布于 2026/09/30MITTypeScriptES Module近 30 天下载 4971

A compiler-first reactive JavaScript UI framework with compile-time JSX and proxy-based stores

原始使用文档
文档目录29 节
  1. Compile To Almost Nothing
  2. Stays Lean When The App Does Work
  3. Philosophy
  4. Performance
  5. Quick Start
  6. TypeScript
  7. Core Concepts
  8. Stores
  9. Class Components
  10. Function Components
  11. Props and Data Flow
  12. Passing components as props
  13. Computed Values
  14. JSX Syntax
  15. Conditional Rendering
  16. List Rendering
  17. Lifecycle
  18. DOM Helpers
  19. Rendering
  20. Router
  21. Quick Example
  22. Route Patterns
  23. Components
  24. Programmatic Navigation
  25. Route Parameters in Components
  26. Related Packages
  27. Documentation
  28. AI-Assisted Development
  29. License
Gea

npm version License: MIT

Gea

A compiler-first reactive JavaScript UI framework with compile-time JSX and proxy-based stores. No virtual DOM — the Vite plugin analyzes your JSX at build time and generates surgical DOM patches that update only what changed. A hello-world production build is 121 B brotli; an equivalent interactive todo ships 4.9 kb of brotli JavaScript.

Svelte made "compile the framework away" famous. Gea takes the phrase literally: in a static hello-world app, the framework runtime disappears from the bundle.

Compile To Almost Nothing

In a fresh Vite production hello-world build, Gea ships 121 B of brotli JavaScript. The equivalent Solid build ships 3.6 kb, Svelte ships 8.5 kb, Vue ships 20.7 kb, and React ships 50.8 kb.

FrameworkVersionRaw minified JSBrotli JSBrotli vs Gea
Gea1.3.0214 B121 B1.0x
Solid1.9.1210,196 B3,601 B29.8x
Svelte5.55.523,461 B8,537 B70.6x
Vue3.5.3358,174 B20,711 B171.2x
React19.2.5 / React DOM 19.2.5189,717 B50,816 B420.0x

Measured from fresh Vite 8.0.10 production apps, summing JavaScript assets only. Gea used the compiled component output; React, Vue, and Svelte used equivalent minimal hello-world components.

Stays Lean When The App Does Work

Hello world proves the compiler can disappear. Todo proves the runtime stays lean when the app actually does something.

In an equivalent interactive todo app with reactive state, input handling, filtering, item updates, and identical CSS, Gea ships 4.9 kb of brotli JavaScript. Solid ships 5.7 kb, Svelte ships 13.7 kb, Vue ships 22.6 kb, and React ships 51.5 kb.

FrameworkVersionMinified JS rawMinified JS brotliTotal raw JS+CSSTotal brotli JS+CSS
Gea1.3.015,364 B4,896 B18,075 B5,664 B
Solid1.9.1216,181 B5,721 B18,892 B6,485 B
Svelte5.55.538,812 B13,661 B41,523 B14,429 B
Vue3.5.3363,676 B22,585 B66,387 B23,411 B
React19.2.5 / React DOM 19.2.5192,330 B51,460 B195,041 B52,287 B

Measured from fresh Vite production builds in /tmp/gea-todo-framework-size-compare. CSS was identical across all builds: 2,711 B raw, 746 B brotli.

Philosophy

Gea's guiding principle is that JavaScript code should be simple and understandable. A framework should not invent new programming concepts or expect you to conform to arbitrary rules. You write regular, idiomatic JavaScript — classes with state and methods, functions that return markup, getters for derived values — and Gea makes it reactive under the hood.

There are no signals, no hooks, no dependency arrays, no compiler directives, and no framework-specific primitives. The only concept Gea introduces is the Store class, which is just an ordinary class whose properties happen to be observed by a proxy. Everything else — class inheritance, method calls, property access, Array.map, ternary expressions — is standard JavaScript you already know.

The "magic" lives entirely in the build step. The Vite plugin analyzes your code at compile time, figures out which DOM nodes depend on which state, and generates the wiring. At runtime, you get clean, readable, object-oriented code that just works.

Performance

Gea is the fastest compiled UI framework — benchmarked with the js-framework-benchmark suite, the industry-standard stress test covering row creation, updates, swaps, selection, and deletion on large tables.

FrameworkWeighted geometric mean
vanillajs1.00
Gea 1.31.02
Solid 1.91.10
Svelte 51.10
Vue 3.61.22
React 19.21.43

Lower is better (1.00 = fastest). Gea outperforms every compiled framework while requiring zero framework-specific concepts — no signals, no hooks, no compiler directives. It's not just the DX — it's the fastest, too. Full benchmark report

Quick Start

npm create gea@latest my-app
cd my-app
npm install
npm run dev

Or add Gea to an existing Vite project:

npm install @geajs/core @geajs/vite-plugin
// vite.config.ts
import { defineConfig } from 'vite'
import { geaPlugin } from '@geajs/vite-plugin'

export default defineConfig({
  plugins: [geaPlugin()]
})

TypeScript

Gea provides full JSX type-checking via TypeScript's jsxImportSource. Add this to your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@geajs/core"
  }
}

This gives you prop autocompletion, type errors on invalid attributes, and hover types in any TypeScript-aware editor — VS Code, Cursor, Vim, Zed — without framework-specific plugins.

Use declare props on class components for typed props:

export default class UserCard extends Component {
  declare props: { name: string; email: string; onSelect?: () => void }

  template({ name, email, onSelect }: this['props']) {
    return (
      <div class="user-card" click={onSelect}>
        <span>{name}</span>
        <span>{email}</span>
      </div>
    )
  }
}

declare props defines the accepted JSX attributes — no JavaScript emitted. : this['props'] on the template() parameter is optional but recommended — it types the destructured variables inside the method for full end-to-end type safety.

Core Concepts

Stores

A Store holds shared application state. Extend Store, declare reactive properties as class fields, add methods that mutate them, and export a singleton instance. The store instance is wrapped in a deep Proxy that tracks every mutation 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()

Mutate state directly — the proxy handles reactivity automatically. Array methods (push, pop, splice, sort, reverse, shift, unshift) are intercepted to produce fine-grained change events like append, reorder, and swap.

Class Components

Extend Component and implement a template() method that returns JSX. Class components inherit from Store, so they have their own reactive properties — use them when you need local, transient UI state that no other component cares about.

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()}). The compiler wires both forms to the component's event delegation system. Use method references for simple forwarding; use arrow functions when you need to pass arguments or compose logic.

Use class components when you need local 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 at build time.

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

Use function components for stateless, presentational UI.

Props and Data Flow

Gea's props follow standard JavaScript semantics — no framework-invented concepts like v-model, emit, or callback-based state lifting. When a parent passes data to a child component, it works exactly like passing arguments to a function in JavaScript:

  • Primitives (numbers, strings, booleans) are passed by value. The child receives a copy. Reassigning the prop in the child does not affect the parent — just like reassigning a function parameter in plain JS.
  • Objects and arrays are passed by reference. The child receives the same proxy the parent holds. Mutating the object or array in the child updates the parent's state and DOM automatically — because it's the same object.
// parent.tsx
import { Component } from '@geajs/core'

export default class Parent extends Component {
  count = 0
  user = { name: 'Alice', age: 30 }
  items = ['a', 'b']

  template() {
    return (
      <div>
        <span>{this.count}</span>
        <span>{this.user.name}</span>
        <span>{this.items.length} items</span>
        <Child count={this.count} user={this.user} items={this.items} />
      </div>
    )
  }
}
// child.tsx
export default function Child({ count, user, items }) {
  return (
    <div>
      <span>{count}</span>
      <span>{user.name}</span>
      <span>{items.length} items</span>
    </div>
  )
}

In this setup:

  • user.name = 'Bob' in the child updates both parent and child DOM — it's the same reactive proxy.
  • items.push('c') in the child updates both — same array reference.
  • count = 99 in the child updates only the child's DOM — the parent still holds the original value.

This is exactly how JavaScript works. There is no emit, no defineModel, no callback wiring for object/array mutations. The framework doesn't add a layer of indirection — it respects the language's native pass-by-value and pass-by-reference semantics.

For deep nesting (grandchild, great-grandchild, etc.), the same rules apply. As long as the same object reference is passed down, any descendant can mutate it and the change propagates up to every ancestor that observes it — because they all share the same proxy.

Passing components as props

Pass components as props to build layouts with multiple named regions — the same idea other frameworks call "named slots," without a separate API.

// Parent passes components as named props
<Layout header={<Title />} sidebar={<Nav />} main={<Content />} />

// Layout renders each region wherever it wants
export default class Layout extends Component {
  template({ header, sidebar, main }) {
    return (
      <div class="layout">
        <aside>{sidebar}</aside>
        <main>{main}</main>
        <header>{header}</header>
      </div>
    )
  }
}

For a single default region, nest content inside the component tags and read children in the child:

// Parent nests content between opening and closing tags
<Card>
  <h2>Title</h2>
  <p>Body text goes here.</p>
</Card>

// Card renders whatever was nested inside it
export default class Card extends Component {
  template({ children }) {
    return <div class="card">{children}</div>
  }
}

Computed Values

Use getters on stores for derived state. They re-evaluate on every access — the Vite plugin tracks which state paths the template reads and triggers updates when those paths change.

class TodoStore extends Store {
  todos = []
  filter = 'all'

  get filteredTodos() {
    const { todos, filter } = this
    if (filter === 'active') return todos.filter(t => !t.done)
    if (filter === 'completed') return todos.filter(t => t.done)
    return todos
  }

  get activeCount() {
    return this.todos.filter(t => !t.done).length
  }
}

JSX Syntax

Gea JSX is close to HTML. Key differences from React:

FeatureGeaReact
CSS classesclass="foo"className="foo"
Event handlersclick={fn} or onClick={fn}onClick={fn}
Input eventsinput={fn} or onInput={fn}onChange={fn}
Keyboard eventskeydown={fn} or onKeyDown={fn}onKeyDown={fn}

Both native-style (click, change) and React-style (onClick, onChange) event attribute names are supported.

Supported event attributes: click, dblclick, input, change, keydown, keyup, blur, focus, mousedown, mouseup, submit, dragstart, dragend, dragover, dragleave, drop.

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

Conditional Rendering

{step === 1 && <StepOne />}
{!done ? <Form /> : <Success />}

List Rendering

<ul>
  {todos.map(todo => (
    <TodoItem key={todo.id} todo={todo} onToggle={() => store.toggle(todo.id)} />
  ))}
</ul>

Always provide a key prop. Gea uses it for efficient list diffing — handling adds, deletes, reorders, and swaps without re-rendering the entire list.

Lifecycle

MethodWhen called
created(props)After constructor, before render
onAfterRender()After DOM insertion and child mounting
onAfterRenderAsync()Next requestAnimationFrame after render
dispose()Removes from DOM, cleans up observers and children

DOM Helpers

MethodDescription
$(selector)First matching descendant (scoped querySelector)
$$(selector)All matching descendants (scoped querySelectorAll)

Rendering

import App from './app'

const app = new App()
app.render(document.getElementById('app'))

Components render once. Subsequent state changes trigger surgical DOM patches — not full re-renders.

Router

Gea includes a built-in client-side router for single-page applications.

Router APIs are part of the main Gea API, so you can import Link, RouterView, and router from @geajs/core.

Quick Example

import { Component, Link, RouterView } from '@geajs/core'
import Home from './views/Home'
import About from './views/About'
import UserProfile from './views/UserProfile'

export default class App extends Component {
  template() {
    return (
      <div class="app">
        <nav>
          <Link to="/" label="Home" />
          <Link to="/about" label="About" />
          <Link to="/users/1" label="Alice" />
        </nav>
        <RouterView routes={[
          { path: '/', component: Home },
          { path: '/about', component: About },
          { path: '/users/:id', component: UserProfile },
        ]} />
      </div>
    )
  }
}

Route Patterns

PatternExample URLParams
/about/about{}
/users/:id/users/42{ id: '42' }
/repo/:owner/*/repo/dashersw/src/index.ts{ owner: 'dashersw', '*': 'src/index.ts' }

Components

  • RouterView — renders the component matching the current URL. Accepts a routes array of { path, component } objects. Supports both class and function components.
  • Link — renders an <a> tag that navigates via history.pushState instead of a full page reload. Modifier keys (Cmd/Ctrl+click) open in a new tab as expected.

Programmatic Navigation

import { router } from '@geajs/core'

router.navigate('/about')          // push new entry
router.replace('/login')           // replace current entry
router.back()                      // history.back()
router.forward()                   // history.forward()

console.log(router.path)           // '/about'
console.log(router.query)          // { q: 'hello' } for ?q=hello

Route Parameters in Components

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).

  • @geajs/mobile — Mobile UI primitives: views, navigation, gestures, sidebar, tabs, pull-to-refresh, infinite scroll.
  • @geajs/vite-plugin — Vite plugin that powers compile-time JSX transforms, reactivity wiring, and HMR.
  • create-gea — Project scaffolder: npm create gea@latest.

Documentation

Full documentation: docs

AI-Assisted Development

This repository includes agent skills that teach AI coding assistants how to work with Gea. In compatible environments, this gives your editor the context it needs to understand Gea's stores, components, JSX conventions, and reactivity model so you can scaffold and iterate on Gea apps with much better AI assistance.

License

MIT — Copyright (c) 2017-present Armagan Amcalar

版本与发布记录

@geajs/core 共发布 33 个版本,首次发布于 2026/03/18;过去 12 个月发布了 33 个版本。

版本发布日期距今
1.5.1latest2026/09/301 个月前
1.5.02026/09/301 个月前
1.4.32026/09/241 个月前
1.4.22026/09/231 个月前
1.4.02026/06/284 个月前
1.3.02026/04/276 个月前

关于 @geajs/core 的常见问题

@geajs/core 是什么?

A compiler-first reactive JavaScript UI framework with compile-time JSX and proxy-based stores

如何安装 @geajs/core?

在项目目录运行 npm install @geajs/core,或使用 pnpm add / yarn add / bun add。

@geajs/core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geajs/core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geajs/core 可以商用吗?

@geajs/core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geajs/core 的下载量有多少?

根据 npm 官方下载统计,@geajs/core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,971 次,日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geajs/core 还在维护吗?

最新版本 1.5.1 发布于 2026/09/30(1 个月前);至今共发布 33 个版本,其中过去 12 个月发布了 33 个;首次发布于 2026/03/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。