@wrdagency/react-islands 1.0.4 → 2.0.0

package/README.md

@@ -1,7 +1,110 @@
-## React Islands
+# React Islands
 
 Created by Kyle Cooper at [WRD.agency](https://webresultsdirect.com)
 
-React Islands is a way of introducing React into static pages. We developed React Islands as a way of introducing React-based interactivity sprinkled into places on WordPress sites (rendered via PHP).
+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).
 
-The ReactIslandsWebpackPlugin automatically creates statically rendered mark-up for each Webpack entry point. This is rendered to a HTML file at build time which can then be hydrated using the `createIsland`.
+## 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 MyComponent from "./components";
+import { createIsland } from "@wrdagency/react-islands";
+
+export const myComponentIsland = createIsland(MyComponent, {
+	name: "my-component",
+});
+```
+
+```
+// ./islands/index.ts
+export * from "./my-component";
+```
+
+On the client you can then render each of those islands. They'll automatically hook into the DOM where the selector is matched (similar to a portal) to create an island of reactivity.
+
+```
+// index.ts
+import * as islands from "./islands";
+import { hydrateIslands } from "@wrdagency/react-islands";
+
+hydrateIslands( islands );
+
+```
+
+Create a pre-render script. You can configure your build tool to use this as a seperate entrypoint.
+
+```
+// prerender.ts
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as islands from "./islands";
+import { prerenderIslands } from "@wrdagency/react-islands/server";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const outDir = path.resolve(__dirname, "ssg");
+
+prerenderIslands({ islands, outDir });
+```
+
+For our example we're using Vite. We'll build our prerendering script.
+
+```
+npx vite build --ssr ./src/prerender.tsx --outDir ./dist
+```
+
+And then we can run that compiled script. It'll create all of our statically rendered islands and put them into the `outDir` we specified.
+
+```
+node ./dist/prerender.js
+```
+
+For convenience we'd recommend setting up a script in your `package.json` for this like so:
+
+```
+"scripts": {
+	"prerender": "npx vite build --ssr ./src/prerender.tsx --outDir ./dist && node ./dist/prerender.js",
+},
+```
+
+## API
+
+### `createIsland`
+
+`(component: React.FC, options: IslandOpts) => Island`
+
+Creates an island.
+
+#### `IslandOpts`
+
+| 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.
+
+### `prerenderIslands`
+
+`(options: PrerenderIslandsOpts) => Promise<void>`
+
+| Option  | Type                   | Description                                                                                                                              |
+| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| islands | Record<string, Island> | The islands the pre-render. The key of the record is not used, it's just useful to accept a record if we're using `import * as Islands`. |
+| ourDir  | string                 | Path of the directory to output the static HTML to. This directory will be emptied before pre-rendering begins.                          |

package/dist/index.d.ts

@@ -1,9 +1,49 @@
-import { WebpackOptionsNormalized, Compiler } from 'webpack';
+import { FC } from 'react';
+import { JsxPreset } from 'rollup';
 
-declare class ReactIslandsWebpackPlugin {
-    createSubCompiler(dir: string, entry: Record<string, any>, options: WebpackOptionsNormalized): Compiler;
-    apply(compiler: Compiler): Promise<void>;
+interface IslandRenderOptions {
+    shouldHydrate: boolean;
+    multiple: boolean;
+    keepChildren: boolean;
 }
-declare function createIsland(name: string, Component: React.FC): void;
+interface IslandOpts extends Partial<IslandRenderOptions> {
+}
+declare class Island {
+    readonly component: React.FC;
+    readonly renderOptions: IslandRenderOptions;
+    constructor(component: React.FC, opts?: IslandOpts);
+    private getProps;
+    private getRoots;
+    render(name: string): void;
+}
+
+/**
+ * Create a higher-order component with certain fixed.
+ *
+ * Useful for quickly creating multiple variants of the same component to use as islands.
+ *
+ * @param component FC<T>
+ * @param setProps Partial<T>
+ * @returns FC<T>
+ */
+declare function withProps<T>(component: FC<T>, setProps: Partial<T>): FC<T>;
+/**
+ * Checks if the current script is running in a pre-render.
+ *
+ * @returns boolean
+ */
+declare function isServer(): boolean;
+
+type BuildOptions = {
+    name: string;
+    input: string;
+    output: string;
+    minify?: boolean;
+    ssg?: boolean;
+    jsx?: JsxPreset;
+    typescript?: boolean;
+    common?: string[] | Record<string, string>;
+};
 
-export { ReactIslandsWebpackPlugin, createIsland };
+export { Island, isServer, withProps };
+export type { BuildOptions };

package/dist/index.js

@@ -1,142 +1,102 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __async = (__this, __arguments, generator) => {
-  return new Promise((resolve, reject) => {
-    var fulfilled = (value) => {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var rejected = (value) => {
-      try {
-        step(generator.throw(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
-    step((generator = generator.apply(__this, __arguments)).next());
-  });
-};
+import { jsx } from 'react/jsx-runtime';
+import { createRoot } from 'react-dom/client';
+import { useRef, useEffect } from 'react';
 
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  ReactIslandsWebpackPlugin: () => ReactIslandsWebpackPlugin,
-  createIsland: () => createIsland
-});
-module.exports = __toCommonJS(src_exports);
-var import_webpack = require("webpack");
-var import_tmp = __toESM(require("tmp"));
-var import_server = require("react-dom/server");
-var import_client = require("react-dom/client");
-import_tmp.default.setGracefulCleanup();
-var ReactIslandsWebpackPlugin = class _ReactIslandsWebpackPlugin {
-  createSubCompiler(dir, entry, options) {
-    const plugins = options.plugins.filter(
-      (plugin) => !(plugin instanceof _ReactIslandsWebpackPlugin)
-    );
-    const compilerOptions = {
-      mode: "development",
-      target: "node",
-      context: process.cwd(),
-      entry,
-      output: {
-        libraryTarget: "commonjs",
-        path: dir,
-        filename: "[name].js"
-      },
-      module: options.module,
-      stats: false,
-      devtool: false,
-      optimization: {
-        minimize: false
-      },
-      plugins
+/**
+ * Internal component for rendering raw HTML in a React component.
+ */
+function RawHTML({ html }) {
+    const ref = useRef(null);
+    // important to not have ANY deps
+    useEffect(() => {
+        if (ref.current) {
+            ref.current.outerHTML = html;
+        }
+    }, []);
+    return jsx("script", { ref: ref });
+}
+/**
+ * Create a higher-order component with certain fixed.
+ *
+ * Useful for quickly creating multiple variants of the same component to use as islands.
+ *
+ * @param component FC<T>
+ * @param setProps Partial<T>
+ * @returns FC<T>
+ */
+function withProps(component, setProps) {
+    return (props) => {
+        return component({ ...props, ...setProps });
     };
-    return (0, import_webpack.webpack)(compilerOptions);
-  }
-  apply(compiler) {
-    return __async(this, null, function* () {
-      let components = [];
-      const options = compiler.options;
-      const entry = typeof options.entry === "function" ? yield options.entry() : options.entry;
-      const { name: dir } = import_tmp.default.dirSync();
-      const { RawSource } = compiler.webpack.sources;
-      compiler.hooks.run.tapAsync(
-        "ReactIslandsWebpackPlugin",
-        (compiler2, callback) => {
-          components = Object.keys(entry);
-          const subCompiler = this.createSubCompiler(dir, entry, options);
-          subCompiler.run((err, stats) => {
-            if (err) {
-              console.error(err);
-              throw new Error("ReactIslandsWebpackPlugin: Error during compile.");
-            }
-            if (stats == null ? void 0 : stats.hasErrors()) {
-              console.log(stats == null ? void 0 : stats.toString());
-              throw new Error("ReactIslandsWebpackPlugin: Failed to compile.");
+}
+/**
+ * Checks if the current script is running in a pre-render.
+ *
+ * @returns boolean
+ */
+function isServer() {
+    return !(typeof window != "undefined" && window.document);
+}
+
+class Island {
+    component;
+    renderOptions;
+    constructor(component, opts = {}) {
+        this.component = component;
+        this.renderOptions = {
+            shouldHydrate: opts.shouldHydrate ?? true,
+            multiple: opts.multiple ?? false,
+            keepChildren: opts.keepChildren ?? false,
+        };
+    }
+    getProps(element) {
+        const { keepChildren } = this.renderOptions;
+        let props = {};
+        try {
+            const json = element.dataset.props || "{}";
+            if (json) {
+                const parsed = JSON.parse(json);
+                if (typeof parsed !== "object" || Array.isArray(parsed)) {
+                    throw new Error(`Parsed JSON is not a valid dictionary object: '${json}'`);
+                }
+                if (parsed) {
+                    // Ignore null.
+                    props = parsed;
+                }
             }
-            callback();
-            console.log("ReactIslandsWebpackPlugin: Compilation complete.");
-          });
         }
-      );
-      compiler.hooks.thisCompilation.tap(
-        "ReactIslandsWebpackPlugin",
-        (compilation) => {
-          for (const name of components) {
-            const file = `${dir}/${name}.js`;
-            const { default: component } = require(file);
-            const markup = (0, import_server.renderToStaticMarkup)(component());
-            compilation.emitAsset(`${name}.html`, new RawSource(markup));
-          }
+        catch (e) {
+            console.warn("Could not parse JSON props for React Island.");
+            console.error(e);
+        }
+        if (keepChildren) {
+            props.children = jsx(RawHTML, { html: element.innerHTML });
         }
-      );
-    });
-  }
-};
-function createIsland(name, Component) {
-  const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
-  if (isBrowser) {
-    document.querySelectorAll(`[data-react-component="${name}"]`).forEach((element) => {
-      const propsJSON = element.getAttribute("data-react-props") || "{}";
-      const props = JSON.parse(propsJSON);
-      (0, import_client.hydrateRoot)(element, Component(props));
-    });
-  }
+        return props;
+    }
+    getRoots(name) {
+        const selector = `[data-island="${name}"]`;
+        const { multiple } = this.renderOptions;
+        const nodes = [...document.querySelectorAll(selector)];
+        if (!nodes) {
+            console.warn(`Could not render React Island because DOM node (${selector}) could not be found.`);
+            return [];
+        }
+        if (nodes.length > 1 && !multiple) {
+            console.warn(`Multiple elements matched React Island selector (${selector}) but multiple was not enabled. Choosing first element as root.`);
+            return [nodes[0]];
+        }
+        return nodes;
+    }
+    render(name) {
+        this.getRoots(name).forEach((element) => {
+            const props = this.getProps(element);
+            const Component = withProps(this.component, props);
+            const root = createRoot(element);
+            root.render(jsx(Component, {}));
+            return root;
+        });
+    }
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ReactIslandsWebpackPlugin,
-  createIsland
-});
-//# sourceMappingURL=index.js.map
+
+export { Island, isServer, withProps };

package/package.json

@@ -1,34 +1,56 @@
 {
+	"type": "module",
 	"name": "@wrdagency/react-islands",
-	"version": "1.0.4",
+	"version": "2.0.0",
 	"description": "",
 	"main": "./dist/index.js",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"src"
+	],
+	"bin": {
+		"react-islands": "./bin/index.cjs"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
 	"scripts": {
-		"build": "tsup"
+		"build": "npx rollup -c rollup.config.js"
 	},
 	"keywords": [
 		"react",
-		"webpack",
-		"static"
+		"islands"
 	],
 	"author": "Kyle Thomas Cooper @ WRD",
 	"license": "MIT",
 	"devDependencies": {
-		"@types/react-dom": "^18.2.23",
-		"@types/tmp": "^0.2.6",
-		"@types/webpack": "^5.28.5",
-		"tsup": "^8.0.2",
-		"typescript": "^5.4.3"
+		"@rollup/plugin-commonjs": "^28.0.6",
+		"@rollup/plugin-json": "^6.1.0",
+		"@rollup/plugin-node-resolve": "^16.0.1",
+		"@rollup/plugin-replace": "^6.0.2",
+		"@rollup/plugin-terser": "^0.4.4",
+		"@rollup/plugin-typescript": "^12.1.4",
+		"@types/command-line-args": "^5.2.3",
+		"@types/command-line-usage": "^5.0.4",
+		"@types/react": "^19.1.8",
+		"@types/react-dom": "^19.1.6",
+		"command-line-args": "^6.0.1",
+		"command-line-usage": "^7.0.3",
+		"rollup": "^4.45.1",
+		"rollup-plugin-dts": "^6.2.1",
+		"rollup-plugin-typescript-paths": "^1.5.0",
+		"tslib": "^2.8.1",
+		"typescript": "^5.4.3",
+		"yocto-spinner": "^1.0.0"
 	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/kyletcooper/react-islands"
 	},
-	"dependencies": {
-		"react-dom": "^18.2.0",
-		"tmp": "^0.2.3",
-		"webpack": "^5.91.0"
+	"peerDependencies": {
+		"react-dom": "^19.1.0"
 	}
 }

package/src/bin/commands/build.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from "fs";
+import { OutputOptions } from "rollup";
+import yoctoSpinner from "yocto-spinner";
+import { createCommonConfig, createRollupConfigs, runRollup } from "../rollup";
+import { Command } from "../util/command";
+
+export default new Command({
+	description: "Build and statically render the islands.",
+	args: [
+		{
+			name: "config",
+			type: String,
+			alias: "c",
+			// @ts-ignore
+			description: "The config file to use.",
+			defaultValue: "islands.config.json",
+		},
+	],
+	callback: async (args) => {
+		const { config } = args;
+
+		const configJson = JSON.parse(readFileSync(config, "utf8"));
+
+		const { islands, ...restConfig } = configJson;
+
+		if (restConfig.common !== false) {
+			const spinner = yoctoSpinner({
+				text: `Creating common dependencies file...`,
+			}).start();
+
+			const commonRollupConfig = createCommonConfig(restConfig);
+			const { output, ...input } = commonRollupConfig;
+			const success = await runRollup(input, output as OutputOptions);
+
+			if (success) {
+				spinner.success(`Succeeded: common dependencies file`);
+			} else {
+				spinner.warning(`Failed: common dependencies file`);
+			}
+		}
+
+		for (const [name, input] of Object.entries(islands)) {
+			const spinner = yoctoSpinner({
+				text: `Creating island ${name}...`,
+			}).start();
+
+			const rollupConfigs = createRollupConfigs({
+				input,
+				name,
+				...restConfig,
+			});
+
+			let hadFailure = false;
+
+			for (const rollupConfig of rollupConfigs) {
+				const { output, ...input } = rollupConfig;
+				const success = await runRollup(input, output as OutputOptions);
+
+				if (!success) {
+					hadFailure = true;
+				}
+			}
+
+			rollupConfigs.map(async (options) => {});
+
+			if (hadFailure) {
+				spinner.warning(`Failed island: ${name}`);
+			} else {
+				spinner.success(`Succeeded island: ${name}`);
+			}
+		}
+	},
+});

package/src/bin/index.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import build from "./commands/build";
+import { commandset } from "./util/command";
+
+commandset({
+	build,
+});

package/src/bin/rollup/console.ts

@@ -0,0 +1,23 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execPromise = promisify(exec);
+
+export const consoleExecute = async (command: string) => {
+	try {
+		const { stdout, stderr } = await execPromise(command);
+
+		if (stdout) {
+			console.log(stdout);
+		}
+
+		if (stderr) {
+			console.error(stderr);
+		}
+
+		return stdout;
+	} catch (e) {
+		console.error(e);
+		throw e;
+	}
+};

package/src/bin/rollup/generation.ts

@@ -0,0 +1,57 @@
+export function createGlobalObject(namespace: string): string {
+	return namespace
+		.split(".")
+		.filter(Boolean)
+		.map((_, index, levels) => {
+			const path = "window." + levels.slice(0, index + 1).join(".");
+			return `${path} = ${path} || {}`;
+		})
+		.join(";\n");
+}
+
+export function assignGlobalProperty(
+	namespace: string,
+	property: string,
+	value: string
+): string {
+	const namespacing = createGlobalObject(namespace);
+	return `${namespacing};\nwindow.${namespace}['${property}'] = ${value};\n`;
+}
+
+export function importPackage(packageName: string): string {
+	return `import * as ${packageNameToProperty(
+		packageName
+	)} from "${packageName}";\n`;
+}
+
+export function importAndGlobalisePackage(
+	packageName: string,
+	globalName: string
+): string {
+	let str = "";
+
+	str += importPackage(packageName);
+	str += `${globalName} = ${packageNameToProperty(packageName)};\n`;
+
+	return str;
+}
+
+export function packageNameToProperty(packageName: string): string {
+	return packageName
+		.replace(/^@/, "")
+		.replace(/\//g, "_")
+		.replace(/[-_](.)/g, (_, c) => c.toUpperCase())
+		.replace(/^[a-z]/, (c) => c.toUpperCase());
+}
+
+export function renderComponentToFile(
+	filename: string,
+	component: string
+): string {
+	return `var server = require('react-dom/server');
+	var fs = require('node:fs/promises');
+	var path = require('node:path');
+const html = server.renderToString( module.exports.component( {} ) );
+const file = path.resolve(__dirname, '${filename}');
+fs.writeFile(file, html, { flag: "w+" });`;
+}