Partials: Loader Script

Prerequisites

• - A root app shell where bootstrap code runs exactly once.
• - Diwa package installed in your app workspace.
• - A clear boundary between server and client code for SSR frameworks.

Step 1: Install the core package

Install the package that includes custom elements and the loader entrypoint.

npm install @diwacopilot/components

Step 2: Create a registration helper

Guard registration so defineCustomElements() is called once even if multiple app modules import your helper.

import { defineCustomElements } from '@diwacopilot/components/loader';

let didRegister = false;

export function ensureDiwaRegistered(): void {
  if (didRegister) return;
  defineCustomElements();
  didRegister = true;
}

Step 3: Run bootstrap in the app shell

Call the helper during client startup in your framework entrypoint or root client component.

'use client';
import { useEffect } from 'react';
import { ensureDiwaRegistered } from './diwa-registration';

export function DiwaBootstrap() {
  useEffect(() => {
    ensureDiwaRegistered();
  }, []);

  return null;
}

Implementation Notes

• - In Next.js App Router, keep the bootstrap code in a client component.
• - Do not call defineCustomElements() on every route change.
• - Use Components Ready guidance for tests that depend on upgraded internals.

Troubleshooting

• - If tags render but do not behave interactively, confirm bootstrap executes before event bindings.
• - If custom events do not fire in tests, await element readiness before assertions.
• - If you see duplicate definition warnings, ensure only one registration helper is used.

Next Actions