feat(plugin): create plugin to integrate modules

package.json

@@ -38,29 +38,30 @@
     "@types/fs-extra": "^11.0.4",
     "@types/lodash": "^4.14.202",
     "@types/minimist": "^1.2.5",
+    "@types/node": "^20.10.6",
     "@types/prompts": "^2.4.9",
     "@types/semver": "^7.5.6",
+    "@typescript-eslint/eslint-plugin": "^6.13.2",
+    "@typescript-eslint/parser": "^6.13.2",
     "eslint": "^8.55.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "^2.29.0",
+    "eslint-plugin-react": "^7.33.2",
     "execa": "^8.0.1",
     "fs-extra": "^11.2.0",
-    "yaml": "^2.3.4",
     "generate-changelog": "^1.8.0",
     "generate-license-file": "^3.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.13.2",
-    "@typescript-eslint/parser": "^6.13.2",
     "husky": "^8.0.3",
     "lint-staged": "^15.2.0",
     "minimist": "^1.2.8",
     "picocolors": "^1.0.0",
     "prettier": "^3.1.0",
     "prompts": "^2.4.2",
     "semver": "^7.5.4",
+    "tsx": "^4.6.2",
     "typescript": "^5.3.3",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-import-resolver-typescript": "^3.6.1",
-    "eslint-plugin-import": "^2.29.0",
-    "eslint-plugin-react": "^7.33.2",
-    "tsx": "^4.6.2"
+    "yaml": "^2.3.4"
   },
   "packageManager": "pnpm@8.3.1",
   "pnpm": {

packages/pages/docs/api/pages.md

@@ -21,6 +21,9 @@
 | [TemplateModule](./pages.templatemodule.md)                   | The type to include in any template file. It defines the available functions and fields that are available to the template.                                                                                |
 | [TemplateProps](./pages.templateprops.md)                     | The shape of the data passed directly to the different template functions with the exception of the render function (getPath, getHeadConfig, etc).                                                         |
 | [TemplateRenderProps](./pages.templaterenderprops.md)         | The shape of the data passed directly to the template's render function. Extends the [TemplateProps](./pages.templateprops.md) interface and has the additions of a path and a relativePrefixToRoot field. |
+| [WidgetConfig](./pages.widgetconfig.md)                       | The exported <code>config</code> function's definition.                                                                                                                                                    |
+| [WidgetModule](./pages.widgetmodule.md)                       | The type to include in any widget file. It defines the available functions and fields that are available to the widget.                                                                                    |
+| [WidgetProps](./pages.widgetprops.md)                         | The shape of the data passed directly to the different widget functions                                                                                                                                    |
 
 ## Variables
 
@@ -47,3 +50,4 @@
 | [TagType](./pages.tagtype.md)                                   | Type that enumerates the allowed types of HTML elements in the document header.                                                                                                                                                         |
 | [Template](./pages.template.md)                                 | The type definition for the template's default function.                                                                                                                                                                                |
 | [TransformProps](./pages.transformprops.md)                     | The type definition for the template's transformProps function. Can be used to alter and/or augement the props (which include the data document) passed into the template at render time.                                               |
+| [Widget](./pages.widget.md)                                     | The type definition for the widget's default function.                                                                                                                                                                                  |

packages/pages/docs/api/pages.widget.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [Widget](./pages.widget.md)
+
+## Widget type
+
+The type definition for the widget's default function.
+
+**Signature:**
+
+```typescript
+export type Widget = () => React.JSX.Element;
+```

packages/pages/docs/api/pages.widgetconfig.md

@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetConfig](./pages.widgetconfig.md)
+
+## WidgetConfig interface
+
+The exported `config` function's definition.
+
+**Signature:**
+
+```typescript
+export interface WidgetConfig
+```
+
+## Properties
+
+| Property                              | Modifiers | Type   | Description                                                                                              |
+| ------------------------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| [name?](./pages.widgetconfig.name.md) |           | string | _(Optional)_ The name of the widget feature. If not defined uses the widget filename (without extension) |

packages/pages/docs/api/pages.widgetconfig.name.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetConfig](./pages.widgetconfig.md) &gt; [name](./pages.widgetconfig.name.md)
+
+## WidgetConfig.name property
+
+The name of the widget feature. If not defined uses the widget filename (without extension)
+
+**Signature:**
+
+```typescript
+name?: string;
+```

packages/pages/docs/api/pages.widgetmodule.config.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetModule](./pages.widgetmodule.md) &gt; [config](./pages.widgetmodule.config.md)
+
+## WidgetModule.config property
+
+The exported config function
+
+**Signature:**
+
+```typescript
+config?: WidgetConfig;
+```

packages/pages/docs/api/pages.widgetmodule.default.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetModule](./pages.widgetmodule.md) &gt; [default](./pages.widgetmodule.default.md)
+
+## WidgetModule.default property
+
+The exported default widget function. This is expected to be a React Component. If undefined then will be used to generate the HTML instead.
+
+**Signature:**
+
+```typescript
+default?: Widget;
+```

packages/pages/docs/api/pages.widgetmodule.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetModule](./pages.widgetmodule.md)
+
+## WidgetModule interface
+
+The type to include in any widget file. It defines the available functions and fields that are available to the widget.
+
+**Signature:**
+
+```typescript
+export interface WidgetModule
+```
+
+## Properties
+
+| Property                                    | Modifiers | Type                                    | Description                                                                                                                                               |
+| ------------------------------------------- | --------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [config?](./pages.widgetmodule.config.md)   |           | [WidgetConfig](./pages.widgetconfig.md) | _(Optional)_ The exported config function                                                                                                                 |
+| [default?](./pages.widgetmodule.default.md) |           | [Widget](./pages.widget.md)             | _(Optional)_ The exported default widget function. This is expected to be a React Component. If undefined then will be used to generate the HTML instead. |

packages/pages/docs/api/pages.widgetprops.__meta.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetProps](./pages.widgetprops.md) &gt; [\_\_meta](./pages.widgetprops.__meta.md)
+
+## WidgetProps.\_\_meta property
+
+Additional metadata added by the toolchain
+
+**Signature:**
+
+```typescript
+__meta: {
+  mode: "development" | "production";
+}
+```

packages/pages/docs/api/pages.widgetprops.md

@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/pages](./pages.md) &gt; [WidgetProps](./pages.widgetprops.md)
+
+## WidgetProps interface
+
+The shape of the data passed directly to the different widget functions
+
+**Signature:**
+
+```typescript
+export interface WidgetProps
+```
+
+## Properties
+
+| Property                                  | Modifiers | Type                                     | Description                                |
+| ----------------------------------------- | --------- | ---------------------------------------- | ------------------------------------------ |
+| [\_\_meta](./pages.widgetprops.__meta.md) |           | { mode: "development" \| "production"; } | Additional metadata added by the toolchain |

packages/pages/etc/pages.api.md

@@ -277,6 +277,28 @@ export interface TemplateRenderProps<T = any> extends TemplateProps<T> {
 // @public
 export type TransformProps<T extends TemplateProps> = (props: T) => Promise<T>;
 
+// @public
+export type Widget = () => React_2.JSX.Element;
+
+// @public
+export interface WidgetConfig {
+  name?: string;
+}
+
+// @public
+export interface WidgetModule {
+  config?: WidgetConfig;
+  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@yext/pages" does not have an export "render"
+  default?: Widget;
+}
+
+// @public
+export interface WidgetProps {
+  __meta: {
+    mode: "development" | "production";
+  };
+}
+
 // Warnings were encountered during analysis:
 //
 // dist/types/src/common/src/template/types.d.ts:165:5 - (ae-forgotten-export) The symbol "ProjectStructureConfig" needs to be exported by the entry point index.d.ts

packages/pages/src/common/src/project/structure.ts

@@ -24,6 +24,8 @@ export interface RootFolders {
 export interface Subfolders {
   /** The templates folder */
   templates: string;
+  /** The widgets folder */
+  widgets: string;
   /** The Node functions folder */
   serverlessFunctions: string; // Node functions
   /** Where to output the bundled static assets */
@@ -142,6 +144,7 @@ const defaultProjectStructureConfig: ProjectStructureConfig = {
   },
   subfolders: {
     templates: "templates",
+    widgets: "widgets",
     serverlessFunctions: "functions",
     assets: DEFAULT_ASSETS_DIR,
     public: DEFAULT_PUBLIC_DIR,

packages/pages/src/common/src/template/internal/types.ts

@@ -13,6 +13,7 @@ import {
 } from "../types.js";
 import path from "node:path";
 import { validateTemplateModuleInternal } from "./validateTemplateModuleInternal.js";
+import { WidgetConfig } from "../../widget/types.js";
 
 /**
  * A domain representation of a template module. Contains all fields from an imported module as well
@@ -71,6 +72,14 @@ export interface TemplateConfigInternal {
   slugField?: string;
 }
 
+/**
+ * The exported `config` function's definition.
+ */
+export interface WidgetConfigInternal {
+  /** The name of the widget feature. If not defined uses the widget filename (without extension) */
+  name: string;
+}
+
 /**
  * The stream config defined in {@link TemplateConfigInternal.stream}.
  */
@@ -165,6 +174,15 @@ export const convertTemplateConfigToTemplateConfigInternal = (
   };
 };
 
+export const convertWidgetConfigToWidgetConfigInternal = (
+  widgetName: string,
+  widgetConfig: WidgetConfig | undefined
+): WidgetConfigInternal => {
+  return {
+    name: widgetConfig?.name ?? widgetName,
+  };
+};
+
 /**
  * Converts a {@link Stream} into a valid {@link StreamInternal}
  * by setting stream.localization.primary: false if a locales array exists.

packages/pages/src/common/src/widget/types.ts

@@ -0,0 +1,47 @@
+import React from "react";
+
+/**
+ * The type to include in any widget file. It defines the available functions and fields that are available
+ * to the widget.
+ *
+ * @public
+ */
+export interface WidgetModule {
+  /** The exported config function */
+  config?: WidgetConfig;
+  /**
+   * The exported default widget function. This is expected to be a React Component.
+   * If undefined then {@link render} will be used to generate the HTML instead.
+   */
+  default?: Widget;
+}
+
+/**
+ * The type definition for the widget's default function.
+ *
+ * @public
+ */
+export type Widget = () => React.JSX.Element;
+
+/**
+ * The exported `config` function's definition.
+ *
+ * @public
+ */
+export interface WidgetConfig {
+  /** The name of the widget feature. If not defined uses the widget filename (without extension) */
+  name?: string;
+}
+
+/**
+ * The shape of the data passed directly to the different widget functions
+ *
+ * @public
+ */
+export interface WidgetProps {
+  /** Additional metadata added by the toolchain */
+  __meta: {
+    /** Specifies if the data is returned in development or production mode */
+    mode: "development" | "production";
+  };
+}

packages/pages/src/index.ts

@@ -4,3 +4,4 @@ export * from "./common/src/template/head.js";
 export * from "./common/src/template/paths.js";
 export * from "./common/src/template/types.js";
 export * from "./common/src/function/types.js";
+export * from "./common/src/widget/types.js";

packages/pages/src/vite-plugin/build/build.ts

@@ -4,6 +4,7 @@ import closeBundle from "./closeBundle/closeBundle.js";
 import { ProjectStructure } from "../../common/src/project/structure.js";
 import { processEnvVariables } from "../../util/processEnvVariables.js";
 import { buildServerlessFunctions } from "../serverless-functions/plugin.js";
+import { buildWidgets } from "../widgets/plugin.js";
 
 const intro = `
 var global = globalThis;
@@ -33,6 +34,7 @@ export const build = async (
       sequential: true,
       handler: async (): Promise<void> => {
         await buildServerlessFunctions(projectStructure);
+        await buildWidgets(projectStructure);
       },
     },
     config: async (): Promise<UserConfig> => {