API Reference

Complete API documentation for all HellaJS packages including core reactive primitives, DOM utilities, state management, routing, and styling solutions.

@hellajs/core

Reactive primitives like signals, computed values, and effects for building reactive applications.

Installation

npm install @hellajs/core

Example

import { signal, computed, effect, batch, untracked } from '@hellajs/core';

// Simple pricing with member discount
const quantity = signal(1);
const price = signal(49.99);
const discount = signal(0); // 0..1 (e.g., 0.15 = 15%)
const userId = signal('guest-123'); // logging-only context

const total = computed(() => quantity() * price() * (1 - discount()));

const cleanup = effect(() => {
  // Read userId without tracking it so changing it won't retrigger this effect
  const uid = untracked(() => userId());
  console.log(`[${uid}] qty=${quantity()} price=$${price().toFixed(2)} -> total=$${total().toFixed(2)}`);
});

// Group updates so the effect runs once
batch(() => {
  quantity(3);
  discount(0.10);
});

// Independent change — effect runs once
price(44.99);

// Change logging-only context without retriggering the effect
userId('member-777');

// Later, stop reacting if needed
cleanup();

@hellajs/css

Type-safe CSS-in-JS solution with reactive styling and automatic vendor prefixing.

Installation

Does not require @hellajs/core as a peer dependency.

npm install @hellajs/core @hellajs/css

Example

import { signal } from '@hellajs/core';
import { css } from '@hellajs/css';

// Create scoped styles
const cardStyle = css({
  padding: '1rem',
  borderRadius: '8px',
  backgroundColor: '#f8f9fa',
  
  // Nested selectors and pseudo-states
  'h2': { marginTop: 0 },
  '&:hover': { 
    backgroundColor: '#e9ecef',
    transform: 'translateY(-2px)'
  },
  
  // Responsive design
  '@media (max-width: 768px)': {
    padding: '0.5rem'
  }
});

const Card = ({ title, children }) => (
  <div class={cardStyle}>
    <h2>{title}</h2>
    {children}
  </div>
);

@hellajs/dom

Utilities for rendering reactive components and managing DOM interactions with lifecycle support.

Installation

npm install @hellajs/core @hellajs/dom

Example

import { signal } from '@hellajs/core';
import { mount } from '@hellajs/dom';

const Counter = () => {
  const count = signal(0);
  
  return (
    <div>
      <h1>Count: {count}</h1>
      <button onClick={() => count(count() + 1)}>
        Increment
      </button>
      <button onClick={() => count(count() - 1)}>
        Decrement
      </button>
    </div>
  );
};

// Mount the component to the DOM
mount(Counter, '#app');

@hellajs/resource

Reactive data fetching with built-in caching, loading states, and error handling.

Installation

npm install @hellajs/core @hellajs/resource

Example

import { signal, effect } from '@hellajs/core';
import { resource } from '@hellajs/resource';

const userId = signal(1);

// Create a resource that depends on reactive state
const userResource = resource(
  (id) => fetch(`/api/users/${id}`).then(r => r.json()),
  { 
    key: () => userId(),
    cacheTime: 60000 // Cache for 1 minute
  }
);

// React to loading states and data
effect(() => {
  if (userResource.loading()) {
    console.log('Loading user...');
  } else if (userResource.error()) {
    console.error('Failed to load user:', userResource.error());
  } else if (userResource.data()) {
    console.log('User loaded:', userResource.data());
  }
});

// Start fetching
userResource.request();

// Change user and refetch
userId(2);
userResource.invalidate(); // Clear cache and refetch with new userId

@hellajs/router

Client-side routing for single-page applications with reactive navigation state.

Installation

npm install @hellajs/core @hellajs/router

Example

import { mount } from '@hellajs/dom';
import { router, navigate } from '@hellajs/router';

mount(<>Loading...</>);

router({
  routes: {
    '/': () => mount(<HomePage />),
    '/users/:id': (params) => mount(<UserProfile id={params.id} />),
    '/settings': {
      before: () => checkAuth(), // Guard route with authentication
      handler: () => mount(<Settings />)
    }
  },
  notFound: () => mount(<NotFoundPage />)
});

// Programmatic navigation
navigate('/users/123');
navigate('/settings');

@hellajs/store

Deeply reactive state management for complex application data with full type safety.

store

Installation

npm install @hellajs/core @hellajs/store

Example

import { effect } from '@hellajs/core';
import { store } from '@hellajs/store';

const userStore = store({
  profile: { name: 'John Doe', age: 30 },
  settings: { theme: 'dark', notifications: true }
});

// React to nested property changes
effect(() => {
  console.log(`${userStore.profile.name()} prefers ${userStore.settings.theme()} theme`);
});

// Update nested properties
userStore.profile.name('Jane Doe');
userStore.settings.theme('light');

// Partial deep updates
userStore.update({ 
  settings: { theme: 'auto' } // Only updates theme, keeps notifications
});