Appscrip Page Builder

The visual editor for React — published as appscrip-page-builder-core.

Build drag-and-drop page editing experiences with your own React components. You own the data; there is no vendor lock-in.

| | | | --- | --- | | npm | appscrip-page-builder-core | | Repository | maheshm13/puck | | Documentation | apps/demo → /documentation (run the demo locally) | | Feature log | FEATURE_LOG.md | | Current version | 0.1.3-experimental | | Based on | Puck / @puckeditor/core 0.22.2 | | License | MIT |

Links

• npm package
• GitHub repository
• Custom features guide
• Field parts guide
• Feature log

What is this?

This package is a modular visual editor for React (including Next.js):

1. Define a config (your components + fields + render)
2. Author pages in the <Puck> editor
3. Persist JSON data
4. Publish with <Render> (or the RSC entry)

On top of Puck 0.22.2, this project adds Appscrip / TFM features for richer design controls, block previews, UI polish, and part-based field selection. See Custom features below.

Install

npm i appscrip-page-builder-core
# or
yarn add appscrip-page-builder-core

Import styles once in your app:

import "appscrip-page-builder-core/puck.css";

Quick start

Editor

// Editor.jsx
import { Puck } from "appscrip-page-builder-core";
import "appscrip-page-builder-core/puck.css";

const config = {
  components: {
    HeadingBlock: {
      label: "Heading",
      fields: {
        children: { type: "text" },
      },
      defaultProps: {
        children: "Hello world",
      },
      render: ({ children }) => <h1>{children}</h1>,
    },
  },
};

const initialData = {};

const save = (data) => {
  // Persist to your API / database
};

export function Editor() {
  return <Puck config={config} data={initialData} onPublish={save} />;
}

Published page

// Page.jsx
import { Render } from "appscrip-page-builder-core";

export function Page({ data }) {
  return <Render config={config} data={data} />;
}

RSC (React Server Components)

import { Render } from "appscrip-page-builder-core/rsc";

Custom features

Full details:

• packages/core/CUSTOM_FEATURES.md
• FIELD-PARTS.md
• Demo docs UI: run the demo and open /documentation

1. Block preview image (previewImage)

Optional image URL(s) on a component config. Shows an info icon in the Blocks drawer; hover reveals the preview. Pass a string for one image, or string[] for a carousel (arrows appear when there is more than one).

Hero: {
  label: "Hero",
  // Single image (still supported):
  // previewImage: "https://your-cdn.com/previews/hero.png",
  previewImage: [
    "https://your-cdn.com/previews/hero-1.png",
    "https://your-cdn.com/previews/hero-2.png",
  ],
  fields: { /* ... */ },
  render: (props) => { /* ... */ },
}

1b. Blocks drawer search and per-editor filtering

The Blocks panel opens with a search box that matches a component's label, its registered name, its keywords, and its category. Add keywords for synonyms the label doesn't carry.

The drawer prop scopes what a given editor offers without touching config.components, so a page containing a hidden block still renders and edits normally.

Hero: {
  label: "Hero",
  keywords: ["banner", "above the fold", "masthead"],
  fields: { /* ... */ },
  render: (props) => { /* ... */ },
}

<Puck
  config={mergedConfig}
  data={data}
  drawer={{
    include: ["BlogHero", "BlogList"], // allowlist for a blog-only editor
    exclude: ["LegacyBanner"],
    filter: (name) => !name.startsWith("Internal"),
    search: true, // set false to hide the search box
  }}
/>

2. Collapse plugin icon rail (header arrow)

Header arrow toggles only the narrow Blocks / Outline / Audit icon rail. The wider content panel (LAYOUT / component list) stays open; use the header PanelLeft icon to hide that.

<Puck
  config={config}
  data={data}
  ui={{ pluginRailVisible: true, leftSideBarVisible: true }}
  onPublish={save}
/>

3. Design fields

Responsive field types for styling. Prefer the use* hooks in the editor so values follow the canvas viewport switcher (field tabs sync with the canvas).

| Field type | Breakpoints | Controls | Hook | | --- | --- | --- | --- | | typography | web / tablet / mobile | color, fontSize, fontWeight, textDecoration, textAlign, textTransform | useTypographyStyle | | spacing | web / tablet / mobile | padding + margin (top/right/bottom/left) | useSpacingStyle | | boolean | web / mobile | true / false per device | useBooleanValue | | surface | web / tablet / mobile | solid/gradient background + border | useSurfaceStyle |

import {
  useTypographyStyle,
  useSpacingStyle,
  useBooleanValue,
  useSurfaceStyle,
} from "appscrip-page-builder-core";

render: ({ title, titleStyle, sectionSpacing, showSubtitle, sectionStyle }) => {
  const titleCss = useTypographyStyle(titleStyle);
  const spacingCss = useSpacingStyle(sectionSpacing);
  const visible = useBooleanValue(showSubtitle);
  const surfaceCss = useSurfaceStyle(sectionStyle);

  return (
    <section style={{ ...spacingCss, ...surfaceCss }}>
      <h1 style={titleCss}>{title}</h1>
      {visible ? <p>Subtitle</p> : null}
    </section>
  );
};

Optional project-wide ranges on config:

const config = {
  typography: { fontSizeMin: 1, fontSizeMax: 90 },
  spacing: {
    paddingMin: 0,
    paddingMax: 200,
    marginMin: 0,
    marginMax: 200,
  },
  components: { /* ... */ },
};

4. Field parts (region-based selection)

Tag fields to visible regions of a component. Click a region on the canvas to narrow the fields panel to those fields only.

1. Declare parts on the component config
2. Tag fields with part: "heading" (etc.)
3. Spread {...puck.part("heading")} on the matching DOM nodes

If labelIcon is omitted, a default Lucide Component icon is shown. See FIELD-PARTS.md. Demo: apps/demo/config/blocks/Hero.

Local development

This is a Yarn + Turborepo monorepo. Node >=20.

yarn
cd apps/demo
yarn dev

Then open:

• Editor playground: http://localhost:3000
• Documentation: http://localhost:3000/documentation

Useful paths:

| Path | Purpose | | --- | --- | | packages/core | Publishable editor package (appscrip-page-builder-core) | | apps/demo | Full playground + /documentation | | apps/docs | Extra docs site (optional) | | recipes/ | Next.js / React Router starters |

Package exports

| Import | Use | | --- | --- | | appscrip-page-builder-core | Client editor (Puck, Render, fields, hooks, plugins) | | appscrip-page-builder-core/rsc | Server-safe Render + data helpers | | appscrip-page-builder-core/puck.css | Full editor styles | | appscrip-page-builder-core/no-external.css | Styles without external font imports |

Credits

Based on Puck (MIT). This repository is the Appscrip / TFM fork maintained at maheshm13/puck and published as appscrip-page-builder-core.

License

MIT © The Puck Contributors and Appscrip.