Axiom Framework

0.9.1 · active · verified Tue Apr 21

Axiom is a modern web framework featuring a unique two-phase rendering architecture, emphasizing high performance through in-memory calculations and zero direct DOM reads. It leverages a reactive programming model, likely based on signals, to manage UI updates efficiently. Currently at version 0.9.1, the framework appears to be under rapid development, with frequent releases focusing on new features like declarative routing, server-side rendering (`renderToString`), portals, reactive context, and form modules, as well as bug fixes and performance improvements. Its core differentiators include its rendering strategy, aiming to eliminate DOM reads for re-renders, and its TypeScript-first approach, providing strong type safety for developers.

Common errors

```
TypeError: App is not a function
```
cause Attempting to use `App` as a function or class constructor instead of a tagged template literal.

fix Ensure `App` is used with backticks for JSX-like syntax: `App`...``.
```
ReferenceError: require is not defined
```
cause Trying to import Axiom components using CommonJS `require()` syntax in an ES Module environment or vice-versa.

fix Use ESM `import` statements: `import { App, render } from 'axiom-framework';`. Ensure your `package.json` has `"type": "module"` if running in Node.js.
```
TS2305: Module 'axiom-framework' has no exported member 'Signal'.
```
cause Incorrectly trying to import a type or a primitive with a capitalized name that is not exported.

fix Use the lowercase `signal` for the reactive primitive: `import { signal } from 'axiom-framework';`. If you need the type, it's typically inferred or accessed via `typeof`.
```
Error: Hydration mismatch: Server and client DOM differ.
```
cause When using `renderToString` (SSR), the HTML generated on the server does not exactly match the initial render of the client-side application.

fix Ensure your server-side rendering logic and client-side application logic are deterministic and produce identical initial HTML structures. Avoid client-only code that alters the initial render.

Warnings

gotcha Axiom Framework is in active, rapid development (currently <1.0.0), implying that APIs might change frequently between minor and even patch versions. Developers should pin exact versions and carefully review release notes for updates.
Fix: Refer to the GitHub repository's change log for specific API changes. Pin exact versions in your `package.json` (e.g., `"axiom-framework": "0.9.1"`) to prevent unexpected breakage.
breaking Version 0.9.0 introduced 'v1 stability contract validation'. While not explicitly marked as a breaking change, this suggests internal API shifts or stricter adherence, which could inadvertently affect code relying on undocumented or previous internal behaviors.
Fix: Thoroughly test existing applications when upgrading to v0.9.0 and later. Consult the GitHub issue tracker or discussions for details on the v1 stability contract.
gotcha Axiom emphasizes a 'zero DOM reads' approach for re-renders. Directly manipulating the DOM outside of Axiom's reactive system can lead to unexpected behavior, desynchronization, or performance issues.
Fix: Always use Axiom's provided APIs (signals, components, effects) to manage UI state and updates. Avoid direct `document.querySelector` or manual DOM mutations on elements managed by Axiom.
gotcha The framework targets modern JavaScript environments, specifically requiring Node.js >=22.0.0 or Bun >=1.0.0. Older Node.js versions or non-ESM environments are not supported.
Fix: Ensure your development and deployment environments meet the specified engine requirements. Use a modern build toolchain that supports ES Modules.

Install

npm install axiom-framework npm
yarn add axiom-framework yarn
pnpm add axiom-framework pnpm

Imports

App
wrong:
```
const App = require('axiom-framework')
```
correct:
```
import { App } from 'axiom-framework'
```
Axiom is designed for modern ES Modules environments and ships with TypeScript types. CommonJS `require` syntax is not supported.
render
wrong:
```
import render from 'axiom-framework'
```
correct:
```
import { render } from 'axiom-framework'
```
The core rendering function is a named export, not a default export.
signal
wrong:
```
import { Signal } from 'axiom-framework'
```
correct:
```
import { signal } from 'axiom-framework'
```
Reactive primitives like `signal` are typically lowercase named exports. If types are needed, use `typeof signal` or `ReturnType<typeof signal>`.
createPortal
```
import { createPortal } from 'axiom-framework'
```
The `createPortal` function allows rendering components outside the main component tree, similar to React Portals.
renderToString
```
import { renderToString } from 'axiom-framework'
```
For server-side rendering (SSR), `renderToString` is the entry point, available since v0.2.6.

Quickstart

Demonstrates creating a basic reactive counter component using Axiom's `App` and `signal` primitives, then rendering it to the DOM.

import { App, render, signal } from 'axiom-framework';

interface CounterProps {
  initialCount: number;
}

function Counter({ initialCount }: CounterProps) {
  const count = signal(initialCount);

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  return App`
    <div>
      <h1>Count: ${count}</h1>
      <button onclick=${increment}>Increment</button>
      <button onclick=${decrement}>Decrement</button>
    </div>
  `;
}

// Render the Counter component into the DOM
render(document.getElementById('app')!, Counter, { initialCount: 0 });

// Example of accessing a signal's value later
// setTimeout(() => console.log('Current count:', count.value), 2000);

view raw JSON →