React Islands

Created by Kyle Cooper at WRD.agency

React Islands is a way of introducing pockets of React into otherwise static pages, with an option for build-type rendering to help with layout shift. We developed React Islands as a way of introducing React-based interactivity sprinkled into places on WordPress sites (rendered via PHP).

Example Setup

Create your island. Here we use an existing component and use our Islands directory to only setup the islands and not for worrying about functionality.

// ./islands/my-component.tsx
import { Island } from "@wrdagency/react-islands";

const MyCompontent: React.FC = () => {
	<p>
		Hello World
	</p>
}

export default new Island(MyComponent, {
	name: "my-component",
});

Create a configuration file for your islands and use the built-in CLI commands to build, watch, or serve them.

// islands.config.json
{
	"islands": {
		"my-component": "./src/islands/my-component.tsx"
	},
	"output": "./dist/",
	"minify": true,
	"ssg": true,
	"typescript": true
}

Run the package CLI commands from your project root:

npx react-islands build --config islands.config.json
npx react-islands watch --config islands.config.json
npx react-islands serve --config islands.config.json

The build command compiles each island and produces the shared output bundle. The watch command rebuilds on file changes. The serve command starts a local dev server with hot reload and prints each island URL.

API

IslandOpts

When you create an Island you can pass the following options,

| Options | Type | Default | Description | | ------------ | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | name | string | Required | The name of the island. Used for the default selector and the filename of pre-rendering. | | selector | string? | [data-hydrate="{{NAME}}"] | The query selector to match for the islands root. | | multiple | boolean? | false | If enabled, the island will by instantiated for every element that matches the selector, not just the first. | | keepChildren | boolean? | false | If enabled, the children props of the island component will be set to the raw HTML of the existing node's children. Experimental. |

withProps

<T>(component: React.FC<T>, props: Partial<T>) => React.FC<T>

Creates a version of your React component with props already set. Useful for creating multiple islands with variants of the same component.

isServer

() => boolean

Checks if the current environment is the server. Useful for disabled certain features not available during the prerender step.