A 1.3kB module that helps you ship your own slice of paradise to any website. Especially useful for Shopify apps or CMS websites.
[![downloads][downloads-badge]][npmcharts] [![version][version-badge]][package] [![Supports Preact and React][preact-badge]][preact] [![MIT License][license-badge]][license]Join our newsletter
{/* ... */}
Portals work with web component islands too!
Join our newsletter
Name: {pokemonData.name}
Number: {pokemonData.id}
Portals work with islands too!
Name: {pokemonData.name}
Number: {pokemonData.id}
( /** * Must be a valid web component element name. See spec for more details: * https://html.spec.whatwg.org/#valid-custom-element-name */ elementName: string, /** * Component you would like to render inside of the web component */ widget: ComponentType
,
) => {
if (customElements.get(elementName) == null) {
class Element extends HTMLElement {
constructor() {
super()
// Create a shadow root
this.attachShadow({ mode: 'open' })
}
}
customElements.define(elementName, Element)
}
const island = createIsland(widget)
return {
...island,
render: (
args: Omit<
Parameters = {
/**
* A WeakMap that yields the mutation observers associated with a particular root. Used for cleaning up observers
* on destroy.
*/
_rootsToObservers: WeakMap
*
* ```
*
* // turns into
*
* ```html
* some other content
* some other content
* some other content
*
* your-widget
*
/** * A valid selector to a script tag located in the HTML document with a type of either `text/props` or `application/json` * containing props to pass into the component. If there are multiple scripts found with the selector, all props are merged with * the last script found taking priority. */ propsSelector?: string /** * Passed in if using for web components */ elementName?: string }) => void /** * Contains the current props used to render the island. */ props: P /** * Triggers a rerenders of the island with the new props given. */ rerender: (props: P) => void /** * Destroys all instances of the island on the page and disconnects any associated observers. */ destroy: () => void } export const createIsland =
( widget: ComponentType
, ) => { const island: Island
= { _rootsToObservers: new WeakMap(), _roots: [], _executedScript: document.currentScript, // @ts-ignore props: {}, render: ({ selector, clean = false, replace = false, inline = false, initialProps = {}, propsSelector, elementName, }) => { let rendered = false const load = () => { /** * We listen for multiple events to render so soon as we do it once * successfully we break early for others. */ if (rendered === true) return const hostElements = getHostElements({ selector, inline, elementName, }) // Do nothing if no host elements returned if (hostElements.length === 0) return const { rootFragments } = mount
({ island, widget, clean, hostElements, replace, // @ts-ignore Not sure how to fix this error initialProps, propsSelector, }) island._roots = island._roots.concat(rootFragments) rendered = true } load() document.addEventListener('DOMContentLoaded', load) document.addEventListener('load', load) }, rerender: (newProps) => { island._roots.forEach((rootFragment) => { renderIsland({ island, widget, rootFragment, props: { ...island.props, ...newProps }, }) }) }, destroy: () => { island._roots.forEach((rootFragment) => { island._rootsToObservers.get(rootFragment)?.disconnect() render(null, rootFragment) }) }, } return island } ================================================ FILE: src/lib.ts ================================================ import { ComponentType, h, render } from 'preact' import { InitialProps, Island } from './island' type HostElement = HTMLElement | ShadowRoot export const isInShadow = (node: HostElement | HTMLOrSVGScriptElement) => { return node.getRootNode() instanceof ShadowRoot } export const isShadowRoot = (x: unknown): x is ShadowRoot => { return x instanceof ShadowRoot } export const formatProp = (str: string) => { return `${str.charAt(0).toLowerCase()}${str.slice(1)}` } export const getPropsFromElement = ( element: HostElement | HTMLOrSVGScriptElement, ) => { // In a shadow dom we replace the host element because it's within the shadow root. However, // we want the props of the autonomous custom element. const targetElement = isInShadow(element) ? (element.getRootNode() as any).host : element const { dataset } = targetElement const props: { [x: string]: any } = {} for (var d in dataset) { // We don't pull props for inherited attributes if (dataset.hasOwnProperty(d) === false) return // data-prop or data-props works! const propName = formatProp(d.split(/(props?)/).pop() || '') if (propName) { props[propName] = dataset[d] } } return props } export const isValidPropsScript = (element: Element) => { return ( // element.tagName.toLowerCase() === 'script' && ['text/props', 'application/json'].includes( element.getAttribute('type') || '', ) ) } export const getInteriorPropsScriptsForElement = (element: HostElement) => { // getElementsByTagName does not exist on shadow roots and within a shadow root // the caller can't place in props scripts if (isShadowRoot(element)) return [] return Array.from(element.getElementsByTagName('script')).filter( isValidPropsScript, ) } export const getPropsScriptsBySelector = (selector: string) => { return Array.from(document.querySelectorAll(selector)).filter( isValidPropsScript, // Checked by filter call ) as HTMLOrSVGScriptElement[] } export const getPropsFromScripts = (scripts: HTMLOrSVGScriptElement[]) => { let interiorScriptProps: any = {} scripts.forEach((script) => { // Swallow any potential errors so we don't throw on someone else's page try { interiorScriptProps = { ...interiorScriptProps, ...JSON.parse(script.innerHTML), } } catch (e: any) {} }) return interiorScriptProps } /** * Get the props from a host element's data attributes * @param {Element} The host element * @return {Object} props object to be passed to the component */ export const generateHostElementProps =
( island: Island
,
element: HostElement,
initialProps = {},
propsSelector: string | undefined | null,
): P => {
const elementProps = getPropsFromElement(element)
const currentScriptProps = island._executedScript
? getPropsFromElement(island._executedScript)
: {}
const interiorScriptProps = getPropsFromScripts(
getInteriorPropsScriptsForElement(element),
)
const propsSelectorProps = propsSelector
? getPropsFromScripts(getPropsScriptsBySelector(propsSelector))
: {}
return {
...initialProps,
...elementProps,
...currentScriptProps,
...propsSelectorProps,
...interiorScriptProps,
}
}
export const getHostElements = ({
selector,
inline,
elementName,
}: {
selector?: string
inline: boolean
/**
* Passed if targeting web components so that mount in can create web components inside of the host elements
*/
elementName?: string
}): HostElement[] => {
const currentScript = document.currentScript
if (inline && currentScript?.parentNode) {
// @ts-ignore Not sure on this one
return [currentScript.parentNode]
}
// Next, try to get the selector from the current script
const maybeSelector = currentScript?.dataset.mountIn
if (maybeSelector) {
return Array.from(
document.querySelectorAll ({
island,
hostElement,
initialProps,
onNewProps,
propsSelector,
}: {
island: Island
hostElement: HostElement
initialProps: any
onNewProps: (props: P) => void
propsSelector: string | undefined | null
}) => {
const observer = new MutationObserver(function (mutations) {
mutations.forEach(function () {
onNewProps(
generateHostElementProps(
island,
hostElement,
initialProps,
propsSelector,
),
)
})
})
const config = { attributes: true, childList: true, characterData: true }
if (island._executedScript) {
observer.observe(island._executedScript, config)
}
getInteriorPropsScriptsForElement(hostElement).forEach((script) => {
observer.observe(script, { ...config, subtree: true })
})
if (propsSelector) {
getPropsScriptsBySelector(propsSelector).forEach((script) => {
observer.observe(script, { ...config, subtree: true })
})
}
/**
* If the host element is a shadow root we want to observe on the host of it.
*
* Example:
* ({
island,
widget,
rootFragment,
props,
}: {
island: Island
widget: ComponentType
rootFragment: RootFragment
props: P
}) => {
island.props = props
render(h(widget, props), rootFragment)
}
export const mount = ({
island,
widget,
hostElements,
clean,
replace,
initialProps,
propsSelector,
}: {
island: Island
widget: ComponentType
hostElements: Array (
island,
hostElement,
initialProps,
propsSelector,
)
if (clean) {
hostElement.replaceChildren()
}
let rootFragment: any
if (replace) {
rootFragment = createRootFragment(
hostElement.parentElement || document.body,
hostElement,
)
} else {
const renderNode = document.createElement('div')
hostElement.appendChild(renderNode)
rootFragment = createRootFragment(hostElement, renderNode)
}
rootFragments.push(rootFragment)
renderIsland({ island, widget, rootFragment, props })
const observer = watchForPropChanges ({
island,
hostElement,
initialProps,
onNewProps: (newProps) => {
renderIsland({ island, widget, rootFragment, props: newProps })
},
propsSelector,
})
island._rootsToObservers.set(rootFragment, observer)
})
return { rootFragments }
}
================================================
FILE: src/tests/helpers/getById.ts
================================================
export const getById = (x: string) => {
const element = document.getElementById(x)
if (element == null) {
throw new Error(`Could not find element with id: ${x}!`)
}
return element
}
================================================
FILE: src/tests/helpers/inlineScript.tsx
================================================
import { createIsland } from '../../island'
import {
mount,
getHostElements,
formatProp,
getInteriorPropsScriptsForElement,
getPropsFromScripts,
generateHostElementProps,
getPropsFromElement,
createRootFragment,
watchForPropChanges,
isValidPropsScript,
renderIsland,
isInShadow,
isShadowRoot,
} from '../../lib'
import { h, FunctionComponent } from 'preact'
/**
* Use this helper when you want to test what it's like to use an inline script to use preact-island. This imports and stubs everything the Babel transforms under
* the hood for Jest to run the things. I'm not sure a better way to test this unless it's importing the dist files but then that requires a build step every time
* we run tests.
*/
export const InlineScript: FunctionComponent<{
widget: any
renderCode: string
id?: string
}> = ({ widget, renderCode, ...rest }) => {
return (
)
}
================================================
FILE: src/tests/island.props.test.tsx
================================================
import { h } from 'preact'
import { createIsland } from '../island'
import { useState } from 'preact/hooks'
import { render, waitFor } from '@testing-library/preact'
import userEvent from '@testing-library/user-event'
import { InlineScript } from './helpers/inlineScript'
import { getById } from './helpers/getById'
const Widget = (props: any) => {
const [toggle, setToggle] = useState(false)
return (
{toggle ? toggled : null}
{JSON.stringify(props)}
)
}
it('should render at the given selector and trigger a rerender (not remount) when new props are passed to the host', async () => {
const user = userEvent.setup()
const r = render(
,
)
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
})
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"bananas"}',
),
)
/**
* We set some local state to the rendered widget to make sure when we update the props that the localized state
* continues to exist!
*/
const buttonToggleNode = r.getByTestId('toggleButton')
user.click(buttonToggleNode)
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
const islandHost = r.getByTestId('island-host')
islandHost.dataset.propTest = 'apples'
// By asserting that toggled is still in the document it shows we didn't accidentally remount
// the component on prop changes
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"apples"}',
),
)
})
it('should render at the given selector and trigger a rerender (not remount) when rerender is called with new props', async () => {
const user = userEvent.setup()
const r = render(
,
)
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
})
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"bananas"}',
),
)
/**
* We set some local state to the rendered widget to make sure when we update the props that the localized state
* continues to exist!
*/
const buttonToggleNode = r.getByTestId('toggleButton')
user.click(buttonToggleNode)
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
island.rerender({ test: 'apples' })
// By asserting that toggled is still in the document it shows we didn't accidentally remount
// the component on prop changes
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"apples"}',
),
)
})
it('should render at the given selector and trigger a rerender (not remount) when new props are passed to the child script props tag', async () => {
const user = userEvent.setup()
const r = render(
,
)
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
})
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"bananas"}',
),
)
/**
* We set some local state to the rendered widget to make sure when we update the props that the localized state
* continues to exist!
*/
const buttonToggleNode = r.getByTestId('toggleButton')
user.click(buttonToggleNode)
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
const scriptProps = r.getByTestId('script-props')
scriptProps.innerHTML = '{"test": "apples"}'
// By asserting that toggled is still in the document it shows we didn't accidentally remount
// the component on prop changes
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"apples"}',
),
)
})
it('should render at the given selector and trigger a rerender (not remount) when new props are passed to the targeted props script', async () => {
const user = userEvent.setup()
const r = render(
,
)
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
propsSelector: '[data-island-props="test-island"]',
})
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"bananas"}',
),
)
/**
* We set some local state to the rendered widget to make sure when we update the props that the localized state
* continues to exist!
*/
const buttonToggleNode = r.getByTestId('toggleButton')
user.click(buttonToggleNode)
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
const scriptProps = getById('inline-script-test')
scriptProps.innerHTML = '{"test": "apples"}'
// By asserting that toggled is still in the document it shows we didn't accidentally remount
// the component on prop changes
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"apples"}',
),
)
})
it('should render at the given selector and trigger a rerender (not remount) when new props are passed to the injected script', async () => {
const user = userEvent.setup()
const r = render(
,
)
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"bananas"}',
),
)
/**
* We set some local state to the rendered widget to make sure when we update the props that the localized state
* continues to exist!
*/
const buttonToggleNode = r.getByTestId('toggleButton')
user.click(buttonToggleNode)
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
const scriptProps = getById('inline-script')
scriptProps.dataset.test = 'apples'
// By asserting that toggled is still in the document it shows we didn't accidentally remount
// the component on prop changes
await waitFor(() => expect(r.getByTestId('toggled')).toBeInTheDocument())
await waitFor(() =>
expect(r.getByTestId('widgetProps').textContent).toEqual(
'{"island":"island","testid":"island-host","test":"apples"}',
),
)
})
================================================
FILE: src/tests/island.selector.test.tsx
================================================
import { h } from 'preact'
import { createIsland } from '../island'
import { render, waitFor, within } from '@testing-library/preact'
import { InlineScript } from './helpers/inlineScript'
const Widget = (props: any) => {
return {JSON.stringify(props)}
}
it('should render at the given selector', async () => {
const r = render()
await waitFor(() => expect(r.queryByTestId('widget')).not.toBeInTheDocument())
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
})
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
`),
)
})
it('should render inline if prop is passed and take highest priority', async () => {
const r = render(
{"island":"island"}
,
)
await waitFor(() =>
expect(r.getByTestId('parent-node').lastChild).toMatchInlineSnapshot(`
{"testid":"parent-node"}
`),
)
})
it('should render using the data-mount-in prop and take priority over a selector if passed', async () => {
const r = render(
,
)
await waitFor(() =>
expect(
within(r.getByTestId('selector')).queryByTestId('widget'),
).not.toBeInTheDocument(),
)
await waitFor(() =>
expect(
within(r.getByTestId('inlineScriptMountIn')).queryByTestId('widget'),
).toBeInTheDocument(),
)
})
it('should pass down default props', async () => {
const r = render()
const initialProps = {
apples: 'yes',
bananas: 1,
kiwis: true,
}
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
initialProps,
})
await waitFor(() =>
expect(r.getByTestId('widget').innerHTML).toEqual(
JSON.stringify({ ...initialProps, island: 'island' }),
),
)
})
it('should render twice if multiple nodes are found from the selector', async () => {
const r = render(
,
)
const initialProps = {
apples: 'yes',
bananas: 1,
kiwis: true,
}
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
initialProps,
})
// NOTE: Notice there is a different between this one and the other test.
// This one render inside of two data-island elements whereas the other
// renders twice inside of the same data widget host element!
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
`),
)
})
it('should render multiple times if render is called twice', async () => {
const r = render()
const initialProps = {
apples: 'yes',
bananas: 1,
kiwis: true,
}
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
initialProps,
})
island.render({
selector: '[data-island="island"]',
initialProps,
})
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
{"apples":"yes","bananas":1,"kiwis":true,"island":"island"}
{"apples":"yes","bananas":1,"kiwis":true,"island":"island"}
`),
)
})
it('should replace the node at given selector if prop is given', async () => {
const r = render()
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
replace: true,
})
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
{"apples":"yes","bananas":1,"kiwis":true,"island":"island"}
{"apples":"yes","bananas":1,"kiwis":true,"island":"island"}
`),
)
})
it('should destroy mounted islands when destroy called', async () => {
const r = render()
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
})
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
{"island":"island"}
`),
)
island.destroy()
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
{"island":"island"}
`),
)
})
it('should destroy mounted islands when destroy called with replace: true', async () => {
const r = render()
const island = createIsland(Widget)
island.render({
selector: '[data-island="island"]',
replace: true,
})
await waitFor(() =>
expect(r.container).toMatchInlineSnapshot(`
`),
)
island.destroy()
await waitFor(() => expect(r.container).toMatchInlineSnapshot(``))
})
================================================
FILE: tsconfig.json
================================================
{
"compilerOptions": {
"target": "es2017",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"forceConsistentCasingInFileNames": true,
"module": "ES2015",
"moduleResolution": "node",
"resolveJsonModule": true,
"isolatedModules": true,
"declaration": true,
"preserveWatchOutput": true,
"jsx": "react",
"jsxFactory": "h",
"jsxFragmentFactory": ""
},
"include": ["src"],
"exclude": ["**/tests/**"]
}
{"island":"island"}