GitHub v1.3.1

Client-Side JavaScript

Guide

Deep dive into Coralite's client-side JavaScript capabilities. Learn to build interactive components using defineComponent, manage state, access DOM refs, and handle data flow from server to client.

Coralite's component system allows you to bundle client-side logic directly with your HTML templates using the defineComponent helper. This guide explains how to create interactive components, manage data flow, and access DOM elements using the "Flat Options" API.

Philosophy: Components as Logic Containers

In Coralite, standard .html pages should remain as declarative consumers. All imperative logic, DOM manipulation, and state management should be reserved for the client block within a component. Avoid using <script> tags in pages to interact with components.

The defineComponent Helper

The defineComponent function is the core of Coralite's component logic. It separates server-side data fetching and attribute coercion from client-side interactivity using four strictly isolated blocks.

javascript
Code copied!
  import { defineComponent } from 'coralite'
  import db from 'node:database' // Stripped from client bundle
  
  export default defineComponent({
    // Inputs: Coerced from HTML attributes
    attributes: {
        initialCount: { type: Number, default: 0 }
    },
  
    // Server-Side: Asynchronous data fetching (runs at build-time)
    async server(context) {
        const user = await db.users.findFirst();
        return { userName: user.name }
    },
  
    // Derived State: Pure functions (Read-Only)
    getters: {
        greeting: ({ state }) => `Hello, ${state.userName}!`
    },
  
    // Client-Side: Controller (Read/Write)
    client({ state, signal, refs, observe, emit, ...pluginContext }) {
        console.log('Component mounted for user:', state.userName)
  
        // Register an observer to react to count changes
        observe('initialCount', (newVal, oldVal) => {
            console.log(`Count changed from ${oldVal} to ${newVal}`)
        })
  
        const btn = refs('btn')
        btn.addEventListener('click', () => {
            state.initialCount++; // Reactive mutation
            emit('count-updated', { count: state.initialCount }); // Dispatch custom event
        }, { signal });
    }
  })

The Client Context

The client block is executed in the browser when the component mounts. It receives a flattened context object via destructuring:

  • state: A Read/Write Reactive Proxy. This unified state contains state from attributes, server state, and getters. Any mutation here triggers a re-render and re-evaluates getters.
  • observe: A function observe(key, callback) to register explicit side-effects on state changes. The callback receives (newValue, oldValue). Observers are automatically cleaned up on component unmount.
  • emit: A helper function emit(name, detail?, options?) to dispatch custom DOM events from the host custom element. Configured with bubbles: true and composed: true by default.
  • refs: A helper function to query DOM elements within the component's root that have a ref attribute.
  • signal: An AbortSignal tied to the component's lifecycle. Always use this to clean up event listeners or abort pending fetch requests when the component unmounts.
  • root: The root HTML element instance of the Web Component.
  • instanceId: A unique identifier string for this specific component instance.
Imperative custom elements need tracked client code

Create custom elements in scanned client code: component/page client() or plugin client functions. Coralite rewrites imperative creation there and records literal tags for dependency tracking. Dynamically imported helper modules are bundled but not scanned, so do not create custom elements inside them. Production builds do not patch DOM APIs; development and testing do, so testing can hide missing production dependency paths.

See the Imperative Components Reference for creation paths, runtime helpers, upgrade timing, ownership, styling, and troubleshooting.

State Observation & Side-Effects (the observe Pattern)

While Coralite components update their templates automatically when state changes, you often need to perform imperative side-effects (such as updating external DOM libraries, sending analytics, or making network requests) in response to state updates. The observe function provides a clean, declarative pattern for handling these state changes.

Registering Observers

Inside the client function, you can call observe(key, callback).

  • Synchronous State Properties: For primitive or synchronous state properties, the callback is invoked synchronously whenever the state property matching the key is modified and its new value differs from its old value.
  • Async Getters: For asynchronous getters (getters returning Promises), the callback fires asynchronously after the Promise resolves, receiving (resolvedNewVal, resolvedOldVal). Coralite tracks dependencies before and after await boundaries and automatically discards stale in-flight resolutions if newer state changes occur before resolution.
javascript
Code copied!
  export default defineComponent({
    getters: {
      async searchResults({ state, signal }) {
        const res = await fetch(`/api/search?q=${state.query}`, { signal })
        return res.json()
      }
    },
    client({ state, observe }) {
      // Observe synchronous properties
      observe('score', (newVal, oldVal) => {
        console.log(`Score changed from ${oldVal} to ${newVal}`)
      })
  
      // Observe async getters (receives resolved values)
      observe('searchResults', (results, oldResults) => {
        console.log('Search results updated:', results)
      })
    }
  })

Best Practices & Safeguards

  • Avoid Mutating State Inside Observers: Modifying state properties inside an observer callback can trigger infinite reactivity loops. If you need to compute derived state, always use the getters block of defineComponent instead.

    In development or testing environments, Coralite will log a warning if it detects a state mutation during observer execution, and will reject direct cyclic mutations to prevent browser freezes:

    text
    Code copied!
    [Coralite Warning]: Cyclic state mutation detected inside an observe() callback. The observer for "score" mutates "score", which it depends on. This causes an infinite reactivity loop. Use getters for derived state instead.
  • Dual Circuit Breaker: Coralite includes a dual circuit breaker (50 consecutive flushes or 100 flushes in 1s) to catch indirect loops and unblock the UI thread in production and development environments.
  • Automatic Lifecycle Cleanup: You do not need to manually unregister observers. Coralite automatically cleans up all registered observers when the component is disconnected from the DOM to prevent memory leaks.

Native Reactivity & Performance

Coralite uses a Lazy Deep Proxy system. Unlike frameworks that recursively make your entire data structure reactive upfront, Coralite only pays the performance cost for nested objects the exact moment they are accessed.

Additionally, Coralite follows the Smart State, Dumb Template philosophy. Instead of a Virtual DOM, Coralite performs direct token replacement ({{ key }}) in the template, making updates extremely fast and memory-efficient.

Using External Libraries

Because Coralite leverages standard ESM, you can use dynamic import() statements directly inside your client function to load client-side JavaScript dependencies and lazy dependency stylesheets (.css). Local and npm package imports are automatically detected by the build tool and bundled for the browser.

javascript
Code copied!
  export async function client({ state, signal, refs }) {
      const [, { default: confetti }] = await Promise.all([
          import('canvas-confetti/confetti.css', { signal }),
          import('https://esm.sh/canvas-confetti@1.6.0')
      ])
  
      const btn = refs('celebrateBtn')
      btn.addEventListener('click', () => {
          confetti();
      }, { signal })
  }

Component Communication & Event Dispatching

Coralite provides a built-in emit(name, detail?, options?) helper on CoraliteScriptContext to send custom events from child components to parent components or external DOM listeners.

When calling emit('user-updated', { name: 'Alice' }), Coralite automatically constructs a native CustomEvent and dispatches it from the component's host element with bubbles: true and composed: true enabled by default. This ensures the event bubbles seamlessly out of Shadow/Light DOM boundaries to parent containers.

javascript
Code copied!
  // Inside a child component's client block
  client({ state, emit }) {
      // Emits a 'user-updated' CustomEvent from host element with bubbles: true & composed: true
      emit('user-updated', { id: state.userId, name: state.userName });
  }

Parent components can listen for child events by targeting child element references using refs inside their own client block:

javascript
Code copied!
  // Inside a parent component's client block
  client({ signal, refs }) {
      const childComponent = refs('childUserCard');
      
      childComponent.addEventListener('user-updated', (event) => {
          console.log('User updated in child component:', event.detail.name);
      }, { signal });
  }