@de-view/coatl-sdk

SDK for mounting Coatl Engine React modules in WordPress.

Provides the core utilities that every Coatl Engine frontend module uses to mount React components into WordPress pages and communicate with REST APIs.

Installation

npm install @de-view/coatl-sdk

Peer dependencies

npm install react react-dom

API

mountCoatlModule<T>(dataKey, render)

Mounts a React component into a WordPress page. Reads inline data injected by PHP (DataProvider) from window[dataKey], extracts the _coatl.root_id config, finds the DOM element, and renders via createRoot.

import { mountCoatlModule } from '@de-view/coatl-sdk'

interface MyData {
  is_logged_in: boolean
  nonce: string
  api_url: string
}

mountCoatlModule<MyData>('coatl-module-example_data', (data) => (
  <MyComponent data={data} />
))

Parameters:

| Param | Type | Description | |-------|------|-------------| | dataKey | string | Key in window where PHP injected the module data | | render | (data: T) => ReactNode | Render function receiving clean data (without _coatl) |

The component is wrapped in an ErrorBoundary that catches render errors and displays a fallback in dev mode.

useCoatlApi<T>(url, nonce, options?)

React hook for fetching data from Coatl Engine REST API endpoints. Handles loading state, errors, abort on unmount, and refetch.

import { useCoatlApi } from '@de-view/coatl-sdk'

function MyComponent({ apiUrl, nonce }: { apiUrl: string; nonce: string }) {
  const { data, loading, error, refetch } = useCoatlApi<UserData>(apiUrl, nonce)

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error: {error}</p>

  return <div>{data?.name}</div>
}

Parameters:

| Param | Type | Description | |-------|------|-------------| | url | string \| null | REST API endpoint URL. Pass null to skip fetch | | nonce | string \| null | WordPress REST nonce (X-WP-Nonce header) | | options | { method?, body? } | Optional HTTP method and JSON body |

Returns: { data, loading, error, refetch }

How it works

1. PHP DataProvider injects lightweight data into the page via wp_add_inline_script
2. The data includes a _coatl.root_id field pointing to the DOM container
3. mountCoatlModule reads the data, finds the element, and mounts your React tree
4. useCoatlApi handles async data fetching from WordPress REST endpoints

License

MIT