Relaxjs

Ship faster with less code.

Web Component library with routing, forms, DI, templating, and i18n. No virtual DOM, no build magic, no surprise re-renders.

• ~20KB gzipped, one dependency
• Native Web Components, zero vendor lock-in
• Use only what you need: forms, routing, DI, i18n are all independent
• No build step required, no compiler, no CLI
• Standard HTML, standard DOM, standard async/await

Why Relaxjs?

Modern frameworks solve problems you might not have. Relaxjs takes the opposite approach:

| Framework Approach | Relaxjs Approach | |-------------------|------------------| | Virtual DOM diffing | Direct DOM manipulation | | Reactive state management | Explicit updates | | Custom template syntax | Standard HTML | | Framework-specific lifecycle | Native Web Component lifecycle | | Magic re-renders | You control what updates | | Custom rendering pipeline | Native async/await everywhere |

Read the detailed comparison

The result: You always know when something ran, why it ran, and what triggered it.

What Relaxjs Adds

Web Components give you encapsulation and lifecycle hooks. Relaxjs fills the gaps:

| Vanilla Web Components | With Relaxjs | |------------------------|--------------| | Manual form serialization | readData(form) returns typed objects (send it directly to backend) | | Query string parsing | Named routes with typed parameters | | DIY validation logic | FormValidator with HTML5 integration | | No component library | Table, Tabs, TreeView, Menu ready to use | | Manual service wiring | Decorator-based dependency injection | | Raw fetch boilerplate | Simple HTTP client for backend calls |

You write less boilerplate while keeping full control.

Installation

npm install @relax.js/core

Quick Examples

Form Handling

Read and write form data with automatic type conversion:

import { setFormData, readData } from '@relax.js/core';

// Populate a form from an object
const user = { name: 'John', email: '[email protected]', age: 30 };
setFormData(form, user);

// Read form data back (with types!)
const data = readData(form);
// { name: 'John', email: '[email protected]', age: 30 }

Supports nested objects (user.address.city), arrays (tags[]), and automatic type conversion for numbers, booleans, and dates.

Form utilities docs

Client-Side Routing

Define routes and let the router handle navigation:

import { defineRoutes, navigate, startRouting } from '@relax.js/core';

defineRoutes([
    { name: 'home', path: '/', componentTagName: 'app-home' },
    { name: 'user', path: '/users/:id', componentTagName: 'app-user' },
    { name: 'settings', path: '/settings', componentTagName: 'app-settings' }
]);

startRouting();

// Navigate programmatically
navigate('user', { params: { id: '123' } });

<r-route-target></r-route-target>

Routing docs

Form Validation

HTML5-style validation with custom rules and error summaries:

import { FormValidator } from '@relax.js/core';

const validator = new FormValidator(form, {
    useSummary: true,
    submitCallback: () => saveData()
});

Validation docs

What's Included

| Feature | Description | |---------|-------------| | Form Utilities | Read/write forms, type conversion, validation | | Routing | Named routes, typed parameters, guards, layouts, multiple targets | | HTML Templates | html tagged templates with data binding and in-place updates | | HTTP Client | Type-safe get/post/put/del with automatic JWT | | WebSocket | Auto-reconnect, message queuing, typed messages | | SSE | Server-Sent Events dispatched as DOM events | | Dependency Injection | Decorator-based DI with constructor and property injection | | i18n | ICU message format, pluralization, locale-aware formatting | | Pipes | 15 built-in data transformations for templates |

Where Relaxjs Fits

Relaxjs is a good choice when:

• You're building a small-to-medium SPA where you want direct control over the DOM
• Your team prefers vanilla Web Components over framework abstractions
• You want gradual adoption - use only the parts you need, no all-or-nothing buy-in
• Bundle size and simplicity matter more than ecosystem breadth
• You want to understand what your code does - no hidden re-renders, no magic proxies, no compiler transforms

Where Relaxjs Doesn't Fit

Relaxjs is not the right tool for everything:

• Large-scale apps with complex state - Relaxjs has no reactive state management, no global store, no computed properties. If your UI has dozens of interdependent data flows, you'll be writing a lot of manual update logic.
• Server-side rendering / static site generation - Relaxjs is client-only. If you need SEO, fast first-paint from the server, or pre-rendered pages, look at Next.js, Nuxt, or SvelteKit.
• Big teams that need a large talent pool - React and Angular developers are everywhere. Finding developers who know Relaxjs (or are willing to learn a small library) is harder.
• Rich ecosystem needs - There's no component marketplace, no DevTools extension, no community middleware. You build what you need or use vanilla JS libraries.
• Mobile / native targets - No React Native equivalent, no Ionic integration. Relaxjs is for the browser.

How It Compares

| | Relaxjs | React | Angular | Vue | Svelte | |---|---|---|---|---|---| | Approach | Web Components | Virtual DOM | Full framework | Virtual DOM | Compiler | | Bundle size | ~20KB gzipped | ~45KB | ~150KB+ | ~33KB | ~2KB runtime | | Learning curve | Low (vanilla TS) | Medium | High | Medium | Low-Medium | | State management | Explicit DOM updates | Hooks / Redux / Zustand | RxJS / Signals | Reactive refs | Stores / runes | | Routing | Built-in (simple) | react-router (separate) | Built-in (full) | vue-router (separate) | SvelteKit | | Forms | Built-in (HTML5 native) | Controlled / uncontrolled | Reactive forms | v-model | bind: | | SSR | No | Yes | Yes | Yes | Yes | | Ecosystem | Small | Massive | Large | Large | Growing | | DI | Built-in | None (Context API) | Built-in | Provide / Inject | None | | i18n | Built-in (ICU) | i18next etc. | Built-in | vue-i18n | i18next etc. | | DevTools | Browser DevTools | React DevTools | Angular DevTools | Vue DevTools | Svelte DevTools | | Community size | Small | Very large | Large | Large | Medium |

Philosophy

This isn't a framework - it's a library. Use what you need:

• Need just form handling? Import setFormData and readData.
• Need routing? Add defineRoutes and r-route-target.
• Need everything? It's all there.

No buy-in required. No migration path to worry about.

Documentation

• Why Relaxjs? - Detailed comparison with frameworks
• Getting Started - Progressive adoption guide (7 levels)
• Architecture
• Form Utilities - Validation, reading/writing, custom form components
• Routing - Routes, guards, layouts, navigation
• HTML Templates - Tagged templates with data binding
• HTTP & WebSocket - REST calls, WebSocket, SSE
• Dependency Injection
• i18n - Translations, ICU format, locale switching
• Pipes - Data transformations for templates
• Utilities - Sequential IDs, LinkedList, helpers

Browser Support

Works in all browsers that support Web Components (Chrome, Firefox, Safari, Edge).

License

MIT