@coherent.js/client

Client-side hydration and HMR utilities for Coherent.js applications.

• ESM-only, Node 20+
• Progressive enhancement for server-rendered HTML
• Lightweight event system and instance lifecycle helpers
• Optional HMR support for dev workflows

For a high-level overview and repository-wide instructions, see the root README: ../../README.md

Installation

pnpm add @coherent.js/client

Requirements:

• Node.js >= 20
• ESM module system

Exports

Client-side hydration and HMR utilities

Modular Imports (Tree-Shakable)

• Hydration utilities: @coherent.js/client
• Client router: @coherent.js/client/router
• HMR support: @coherent.js/client/hmr

Example Usage

import { hydrateComponent } from '@coherent.js/client';
import { createClientRouter } from '@coherent.js/client/router';

Note: All exports are tree-shakable. Import only what you need for optimal bundle size.

Quick start

The client package pairs with server-rendered HTML produced by @coherent.js/core.

JavaScript (ESM):

import { autoHydrate } from '@coherent.js/client';

// Hydrate elements that were marked as hydratable on the server
autoHydrate();

TypeScript:

import { autoHydrate } from '@coherent.js/client';

document.addEventListener('DOMContentLoaded', () => {
  autoHydrate();
});

Attaching custom handlers

The client exposes an event registry you can populate during hydration.

import { registerEventHandler } from '@coherent.js/client';

registerEventHandler('increment', (el, evt, ctx) => {
  // custom logic using element, DOM event, and context
});

TypeScript:

import { registerEventHandler } from '@coherent.js/client';

type Ctx = { state?: unknown };

registerEventHandler('increment', (el: HTMLElement, evt: Event, ctx: Ctx) => {
  console.log('clicked', el, ctx);
});

Notes on testing

When testing client-side utilities in Node, provide light DOM shims (see repository tests under packages/client/test/). Example:

import { vi } from 'vitest';

global.window = { __coherentEventRegistry: {}, addEventListener: vi.fn() };
global.document = { querySelector: vi.fn(), querySelectorAll: vi.fn(() => []) };

Development

Run tests for this package:

pnpm --filter @coherent.js/client run test

Watch mode:

pnpm --filter @coherent.js/client run test:watch

Type check:

pnpm --filter @coherent.js/client run typecheck

Build:

pnpm --filter @coherent.js/client run build

License

MIT © Coherent.js Team