---
title: "Controller Tooling & HMR"
description: "How RadiantController registration behaves by default, when to use explicit replacement, and how to opt in under Vite and under `ecopages dev`, and what a save does to live controllers."
order: 1
---

# Controller Tooling & HMR

`RadiantController` registration is intentionally stable by default.

That stability matters because controller identifiers are global and controller runtimes may already have live instances attached to DOM nodes by the time another module evaluates.

## Default Contract

The default registry contract is:

- `@controller(...)` uses first-registration-wins semantics
- `registerController(...)` keeps the original class for an identifier
- a later registration does not mutate already-connected instances

That is the safe runtime contract for application code.

It prevents accidental double imports, repeated side-effect evaluation, or duplicate bundle edges from silently swapping controller behavior underneath a live page.

## Explicit Mutation Path

When tooling really does need mutation, the registry exposes separate opt-in APIs through `@ecopages/radiant/controller-registry`.

Use these APIs deliberately:

- `replaceController(identifier, ControllerClass)` replaces the registered class and reconnects matching live hosts
- `enableControllerReplacementForHmr()` switches decorator-driven registration into replacement mode for the current runtime

Vite sets `import.meta.hot` in development, so a Vite app can gate the opt-in on it:

```ts
import { enableControllerReplacementForHmr } from '@ecopages/radiant/controller-registry';

if (import.meta.hot) {
	enableControllerReplacementForHmr();
}
```

That helper is intentionally named for tooling. It is not meant as normal application setup.

## Ecopages

Under `ecopages dev`, `import.meta.hot` is never set, so the guard above never fires and controller replacement stays off. Ecopages also exposes no public development flag for browser code, so you gate the call yourself. Import the helper from a browser entry that you only load in development, and call it before the controller modules evaluate:

```ts
import { enableControllerReplacementForHmr } from '@ecopages/radiant/controller-registry';

enableControllerReplacementForHmr();
```

Replacement mode only changes what happens when a controller module is evaluated a second time, which happens when Ecopages re-imports a changed module. It does not stop the page from re-rendering:

- When the saved module is the active page module, Ecopages asks the router to reload the current page. The browser router morphs the body and replaces custom-element hosts, so each host gets `disconnectedCallback` and then `connectedCallback`.
- That replacement can reset controller state whether controller replacement is on or off.

Treat controller state as disposable during `ecopages dev`.

## Docs-App Integration

This docs app re-exports `enableControllerReplacementForHmr` from [apps/docs/src/utils/radiant-browser-runtime.ts](https://github.com/ecopages/radiant/blob/main/apps/docs/src/utils/radiant-browser-runtime.ts), but it does not call it. The shared browser shell does not enable replacement, so docs pages use the default registration contract.

## Shared Runtime Integration

The Ecopages JSX browser-runtime bootstrap only installs the Radiant hydrator:

```ts
import { installRadiantHydrator } from '@ecopages/radiant/client/hydrator';
installRadiantHydrator();
```

It does not import `enableControllerReplacementForHmr()`. An application that wants replacement under `ecopages dev` adds the call itself, as in the Ecopages section above.

## Design Debt To Keep Visible

The global browser bootstrap belongs to the JSX plugin, while controller registration belongs to the Radiant runtime. Until the bootstrap has an extension point for Radiant setup, each application owns its development-only opt-in.

That is better than making `@controller(...)` mutating by default.

## Recommendation

Use this rule:

- application runtime: keep default registration semantics
- tooling and HMR: opt into explicit replacement
- framework integration: call the opt-in from the highest development-only browser entry you control

For this repo today, that highest shared bootstrap is the base layout script.

For Ecopages JSX generally, the right eventual destination is the plugin runtime bundle service.

## See Also

- [RadiantController](/docs/components/radiant-controller)
- [@controller](/docs/decorators/controller)
