@banulakwin/inertia-page-builder

Types and helpers for banulakwin/laravel-page-builder + Inertia.js dynamic section fields. Pairs with banulakwin/filament-page-builder for the admin UI.

Installation

npm install @banulakwin/inertia-page-builder

pnpm add @banulakwin/inertia-page-builder

yarn add @banulakwin/inertia-page-builder

Peer Dependencies

• react ^18.0.0 || ^19.0.0
• @inertiajs/react ^1.0.0 || ^2.0.0 || ^3.0.0

Quick Start

import {
    parsePageSection,
    type PageBuilderPageData,
} from '@banulakwin/inertia-page-builder';

// From Laravel: PageService::getPage() (your Inertia prop may be named `page` or `cms`)
const page: PageBuilderPageData = props.page;

const header = parsePageSection(page, 'about-header');

// With field definitions (optional third argument)
const headerWithDefs = parsePageSection(
    page,
    'about-header',
    pageDefinitions?.['about-header'],
);

Pass pageDefinitions from PageRegistry::publicFieldMetadataBySection($pageKey) on the Laravel side.

API Reference

Types

PageBuilderPageData

Raw page data from PageService::getPage().

type PageBuilderPageData = Record<string, Record<string, string | null | undefined>>;

PageBuilderSectionPayload

Parsed section shape for React components.

type PageBuilderSectionPayload = {
    slug: string;
    fields: Record<string, string | null>;
    definitions?: PageBuilderSectionFieldDefinitions;
};

PageBuilderFieldDefinition

Recursive field definition: type, label, meta, disk, path, fields.

PageBuilderSectionFieldDefinitions

Record<string, PageBuilderFieldDefinition> for one section.

PageBuilderImageMetaHints

Image layout hints: aspectRatio, crop, width, height, mobile variants, sizes, objectPosition, etc.

PageBuilderRepeaterLinkItem

type PageBuilderRepeaterLinkItem = {
    label: string;
    url: string;
};

Functions

parsePageSection(page, sectionSlug, definitions?)

Main entry point — parses a section into PageBuilderSectionPayload. Returns undefined if the section is missing.

parsePageRepeaterJson(raw)

Parses JSON from page_contents into unknown[].

pageRepeaterTextLines(raw)

Extracts { text: string } rows from repeater JSON.

pageRepeaterRichHtmlBlocks(raw)

Extracts HTML blocks for dangerouslySetInnerHTML (content should be sanitized server-side).

pageRepeaterLinkItems(raw)

Extracts { label, url } items from repeater JSON.

pageImageMetaFromDefinition(def)

Image meta hints from a field definition.

resolvePagePublicImageUrl(raw)

Normalizes image paths to public URLs (/storage/..., /img/..., or absolute URLs).

pageImageMeta(definitions, fieldKey)

Image meta for a top-level field key.

pageNestedSubfield(parent, fieldKey)

Sub-field inside a repeater or group definition.

Migration from workspace Cms* API (v1)

If you copied an older local package that used Cms / cms prefixes:

| Old | New | |-----|-----| | CmsPageData | PageBuilderPageData | | CmsPublicFieldDefinition | PageBuilderFieldDefinition | | CmsSectionFieldDefinitions | PageBuilderSectionFieldDefinitions | | CmsSectionPayload | PageBuilderSectionPayload | | CmsImageMetaHints | PageBuilderImageMetaHints | | CmsRepeaterLinkItem | PageBuilderRepeaterLinkItem | | parseCmsSection | parsePageSection | | parseCmsRepeaterJson | parsePageRepeaterJson | | cmsRepeaterTextLines | pageRepeaterTextLines | | cmsRepeaterRichHtmlBlocks | pageRepeaterRichHtmlBlocks | | cmsRepeaterLinkItems | pageRepeaterLinkItems | | cmsImageMetaFromDefinition | pageImageMetaFromDefinition | | cmsImageMeta | pageImageMeta | | cmsNestedSubfield | pageNestedSubfield | | resolveCmsPublicImageUrl | resolvePagePublicImageUrl |

Build

npm run build

License

MIT

See Also

• AGENTS.md — page builder payload contract and AI agent guide
• CHANGELOG.md — release history
• banulakwin/laravel-page-builder
• banulakwin/filament-page-builder