Next.js: Getting Started
Register Diwa custom elements in a client-side bootstrap component and use them in App Router pages.
Packages: @diwacopilot/components
Prerequisites
- - Node.js 20+ and npm/pnpm/yarn.
- - A project scaffold for your framework (Vite, Next.js, Angular CLI, or Vue tooling).
- - Basic familiarity with custom-element event handling.
Step 1: Install Packages
Install the required package set for this framework integration.
npm install @diwacopilot/componentsStep 2: Register and Initialize
Register components once at app startup so every page can render Diwa elements correctly.
// app/diwa-client.tsx
'use client';
import { useEffect } from 'react';
import { defineCustomElements } from '@diwacopilot/components/loader';
export function DiwaClient() {
useEffect(() => {
defineCustomElements();
}, []);
return null;
}
// app/layout.tsx
import { DiwaClient } from './diwa-client';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<DiwaClient />
{children}
</body>
</html>
);
}Step 3: Render Your First Component
Start with a simple action component to verify styling, registration, and framework rendering.
export default function Page() {
return <diwa-button variant="primary">Save</diwa-button>;
}Step 4: Handle Events
Wire event handling early to validate data flow and interaction behavior in your app.
'use client';
import { useEffect, useRef } from 'react';
export function SaveButton() {
const ref = useRef<HTMLElement | null>(null);
useEffect(() => {
const node = ref.current;
if (!node) return;
const onClick = () => console.log('Save clicked');
node.addEventListener('click', onClick);
return () => node.removeEventListener('click', onClick);
}, []);
return <diwa-button ref={ref} variant="primary">Save</diwa-button>;
}SSR and Testing Notes
- - Call defineCustomElements() only on the client.
- - For server rendering with custom elements, keep interactive logic in client components.
- - Use browser-based tests for hydration and keyboard behavior; use unit tests for static rendering checks.
Troubleshooting
- - If hydration warnings appear, ensure your bootstrap component is marked with use client.
- - If the element tag stays unupgraded, verify defineCustomElements() runs before interaction code.
- - If SSR and client markup differ, avoid mutating custom-element props during the first render pass.