Add mechanism for prop migration

[chrisvxd]

Problem

Source: https://news.ycombinator.com/item?id=37392861

Sometimes a user might need to rename or remove a property provided to a component. For example, remaining description to subtitle.

The user currently has two options:

1. Manually migrate their saved data before updating their Puck configuration
2. (Preferred) Retain the old prop and map it to the new prop inside the render function.

These solutions either require repetitive work, or require the user to republish each page manually.

Proposal

Add a first-party mechanism for transforming data on a per-component basis.

This would probably live under a separate package (/packages/transform or /packages/migrate) and provide a user with a mechanism to 1) patch their data on the fly in a standardised manor and 2) batch transform their puck data consistently to adhere to the new props.

Create transformer

import { createTransform } from "@measured/puck-transform";

const transform = createTransform({
  HeadingBlock: ({ subtitle, ...props }) => {
    return {
      ...props,
      description: subtitle,
    };
  },
});

Patch data inline

// Pull from backend
const data = {
  type: "HeadingBlock",
  props: {
    subtitle: "Hello, world",
  },
};

export default () => <Puck data={transform(data)} config={config} />;

Patch all existing data

// Example data
const allData = [
  {
    path: "/",
    data: {
      root: {},
      content: [
        {
          type: "HeadingBlock",
          props: {
            subtitle: "Hello, world",
          },
        },
      ],
    },
  },
];

// Run the transformer
const patchedData = allData.map((page) => ({
  ...page,
  data: transform(page.data),
}));

// Write to your db
const save = () => {};
save(patchedData);

Considerations

• TypeScript - How to tightly manage the types?

[chrisvxd]

Additional, related concern - renaming components (not just props)

May wish to consider expanding the proposals above to capture this use case, too.