@planningcenter/tapestry-wrap

Summary

This tool allows you to wrap React components as web components. There are similar tools such as remount, but this tool allows you to use nested components in a performant way.

Quickstart

1. Add the package:

yarn add @planningcenter/tapestry-wrap

2. Add your components to the registry and run connect:

Take for instance you had a component like this:

function MyComponent({ children, disabled, title, count, data }) {
  return (
    <div className={disabled ? "disabled" : "active"}>
      <h1>{title}</h1>

      <h2>Welcome {data.attributes.name}!</h2>

      <span>
        You have: {count}. You have {20 - count} left!
      </span>
    </div>
  )
}

You can use it like this:

import { registry } from "@planningcenter/tapestry-wrap"
// use the legacy import if you use React 17.
// import { registry } from "@planningcenter/tapestry-wrap/legacy"



registry.add("prefix-my-component", MyComponent, {
  children: "node",
  disabled: "boolean",
  title: "string",
  count: "number"
  data: "json"
})
registry.connect()

1. Use the component in your html

<prefix-my-component
  disabled
  title="Form"
  count="1"
  data='{"id":1,"attributes":{"name": "Bart"}}'
>
  <button>Submit</button>
</prefix-my-component>

Notes

Interface is designed to work like a native component, not a React component

For this reason, attributes like boolean follow html standards (boolean is true if active="active", active="" or active). Values are then converted to the correct type for the React components. For this reason, defaulting a boolean to true does not work (as there is no way of explicitly saying false).

Do not use React wrapped web components inside the body of a React component

Because this uses the rendering engine of ReactDOM, usage inside an already mounted React component will cause problems. Instead, just use the original component in react and use the wrapped component in your html.

Why run connect?

Because web components execute immediately if the DOM is loaded, if you register an external component before a nested component, it won't be able to detect that it is registered.

To avoid this, make sure to register all components before running connect