create-sitecore-jss 22.2.1 → 22.3.0-canary.10

package/dist/templates/node-xmcloud-proxy/README.md

@@ -0,0 +1,130 @@
+# Node XM Cloud Proxy
+
+> Sitecore JSS Proxy for XM Cloud is considered experimental.
+
+[Documentation](TODO)
+
+This proxy will serve as the backbone for supporting various SPA frameworks by handling server-side rendering (SSR), data queries, and middleware functionalities.
+
+This is a sample setup showing one of how you can configure XM Cloud rendering server.
+
+## Features Supported
+
+- `Context ID`: The Context ID environment variable simplifies setting up and configuring XM Cloud solutions. It's a unified identifier that maps to all your configured resources, such as content, sites, files, forms, and integration settings.
+
+- `Pages new editing integration via HTTP render engine endpoint`: Before JSS 22.1, JSS Next.js apps integrated with Sitecore editors through chromes, where data was sent via a POST request. With the 22.1 release, a new metadata method was introduced, rendering the app inside an iframe in XM Cloud Pages, offering benefits like faster load times, simpler configuration, and direct local host connections without tunneling.
+
+- `XM Cloud proxy personalization` with embedded personalization and A/B Component Test support.
+
+- `Forms support`: provides the capability to consume and post Sitecore Forms from JSS apps. Sitecore Forms is a form-authoring framework that enables marketers to author their own forms, collect data, and analyze form performance.
+
+## Configuration Setup
+
+The config.ts file in this proxy app handles essential configurations for server-side rendering, data queries, and middleware functionalities. Here are the main configurations defined:
+
+- Server Bundle Configuration:
+
+  - The app loads a server.bundle.js file, pre-built from your SPA app, for SSR support.
+  - This file contains the configuration and factory functions essential for rendering and data querying.
+
+- GraphQL Endpoint Setup:
+
+  - Defines a graphQLEndpoint for handling Sitecore GraphQL requests. It differentiates between production (Sitecore Edge) and development (Sitecore CM) endpoints.
+  - Constructs the target URL and path for proxy requests, ensuring compliance with http-proxy-middleware requirements.
+
+- Port Configuration:
+
+  - Configures the port for running the proxy, with a default of 3000 or an environment-specified port.
+
+- Personalization Configuration (personalizeConfig):
+
+  - Sets up Sitecore personalization through PersonalizeConfig, defining settings for both Sitecore Experience Edge and CDP endpoints.
+  - Contains options to control personalization features, including:
+    - Timeouts for Edge and CDP endpoints (default 400ms, configurable via environment variables).
+    - Scope and site name used for Sitecore Personalize.
+    - Enable/Disable Switch: Functions that allow you to conditionally disable personalization based on the environment (e.g., disabled in development mode) and cookie consent policy.
+    - Language Configuration: defaultLanguage serves as a fallback if language data is unavailable in layout data.
+
+This configuration is designed to be flexible and secure, with dynamic settings managed via environment variables where appropriate.
+
+### Environment Variables
+
+The following environment variables can be set to configure the Proxy sample instead of modifying `config.js`. You can use the `.env` file located in the root of the app or set these directly in the environment (for example, in containers).
+
+| Parameter           | Description                                                                                                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PROXY_BUNDLE_PATH` | Path to the JSS SPA app's `server.bundle.js`. Default can be seen in [config.js](./config.js) file.                                                                                          |
+| `PROXY_PORT`        | Optional. Port which will be used when start sample. Default can be seen in [config.js](./config.js) file.                                                                                   |
+| `DEBUG`             | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:_,proxy_,http-proxy-middleware\*, 'sitecore-jss:layout','sitecore-jss:personalize' to see all logs. |
+
+## Pre-requisites
+
+1. SPA sample supports XM Cloud out of the box.
+
+2. Build your SPA app bundle with `jss build` or `npm run build`. The build output should be placed in the `dist` folder. |
+
+## Build & run
+
+1. Run `npm install`
+
+2. Run `npm run start`
+
+You should be able to see the following message:
+`server listening on port 3000!`.
+
+## Deploy to Netlify
+
+`NOTE: If you are using the Angular starter from the XM-Cloud Foundation repository within a monorepo, please skip to Step 3.`
+
+1. Run `npm init` in the root directory and add the following scripts to package.json:
+   ```
+      "build": "cd ./<your-proxy-app-name> && npm run build-all && cd ..",
+      "install": "cd ./<your-proxy-app-name> && npm install && npm run install-all && cd ..",
+   ```
+2. Ensure that `<your-proxy-app-name>/package.json` includes the following commands to handle the build and install steps properly::
+   ```
+      "build-all": "cd ../angular && npm run build && cd ../<your-proxy-app-name> && tsc",
+      "install-all": "cd ../angular && npm i && cd ../<your-proxy-app-name>"
+   ```
+3. Add `serverless-http` to the list of dependencies in `<your-proxy-app-name>/package.json` and then add the following variable to your ``<your-proxy-app-name>/src/index.ts` file.
+    ```
+      export const handler = serverless(server);
+    ```
+4. Create a `netlfiy.toml` file if not already created and ensure that the following Netlify configuration is added there:
+   - Following functions lets the proxy app to treated as netlify functions. [Functions Overview](https://docs.netlify.com/functions/overview/)
+     ```
+        [functions]
+        directory = "<your-proxy-app-name>/src"
+        node_bundler = "esbuild"
+        included_files = ["<your-proxy-app-name>/dist/**"]
+     ```
+   - To ensure that static assets are accessed properly we may need to add redirects statement for them to the toml file:
+     ```
+        [[redirects]]
+        from = "/dist/browser/*"
+        status = 200
+        to = "/browser/:splat"
+     ```
+   - To ensure that static files under /dist are not accessible via browser add `force=true` to the above
+     ```
+       [[redirects]]
+       from = "/*"
+       status = 200
+       to = "/.netlify/functions/index/:splat"
+       force = true
+     ```
+   - Build command
+     ```
+     [build]
+     command = "npm run build"
+     publish = "<your-proxy-app-name>/dist"
+     ```
+5. Create your netlify deployment: [A Step-by-Step Guide: Deploying on Netlify | Netlify](https://www.netlify.com/blog/2016/09/29/a-step-by-step-guide-deploying-on-netlify/)
+   a. Set up all your necessary environment variables like SITECORE_EDGE_CONTEXT_ID, SITECORE_SITE_NAME etc.
+   b. Set up your build settings in Site configuration --> Build and Deploy tab.
+      sample configuration:
+        Base Directory: /
+        Build command: npm run build
+        Publish directory: /proxy/dist
+        Functions directory: /proxy/src
+   NOTE: If proxy/dist folder is not picked up properly by Netlify make sure that the `PROXY_BUILD_PATH` env variable is unix style path e.g. `../proxy/dist`

package/dist/templates/node-xmcloud-proxy/gitignore

@@ -0,0 +1,33 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# compiled output
+/dist
+
+# dependencies
+/node_modules
+
+# local env files
+.env.local
+.env.*.local
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+/connect.lock
+/libpeerconnection.log
+npm-debug.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db
+
+# deploy platforms
+.vercel
+.netlify

package/dist/templates/node-xmcloud-proxy/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "node-xmcloud-sample",
+  "version": "22.3.0-canary",
+  "description": "Node XM Cloud Proxy sample for running XM Cloud JSS SPA apps",
+  "author": {
+    "name": "Sitecore Corporation",
+    "url": "https://jss.sitecore.com"
+  },
+  "scripts": {
+    "start": "ts-node ./src/index.ts"
+  },
+  "dependencies": {
+    "@sitecore-jss/sitecore-jss-proxy": "~22.3.0-canary",
+    "compression": "^1.7.4",
+    "express": "^4.18.2",
+    "dotenv": "^16.0.3",
+    "http-proxy-middleware": "^3.0.0"
+  },
+  "devDependencies": {
+    "@sitecore-jss/sitecore-jss": "~22.3.0-canary",
+    "@types/compression": "^1.7.2",
+    "@types/express": "^4.17.17",
+    "ts-node": "^10.9.1",
+    "typescript": "~4.9.5"
+  }
+}

package/dist/templates/node-xmcloud-proxy/src/config.ts

@@ -0,0 +1,91 @@
+import { Config, ServerBundle } from './types';
+import { PersonalizeConfig } from '@sitecore-jss/sitecore-jss-proxy';
+/**
+ * The server.bundle.js file from your pre-built SPA app.
+ */
+const bundlePath = process.env.PROXY_BUNDLE_PATH || '../dist/server.bundle';
+
+let serverBundle: ServerBundle;
+
+try {
+  serverBundle = require(bundlePath);
+} catch (error) {
+  throw new Error(`ERROR: The server.bundle.js error. ${error}`);
+}
+
+const clientFactoryConfig = serverBundle.getClientFactoryConfig();
+
+/**
+ * GraphQL endpoint resolution to meet the requirements of the http-proxy-middleware
+ */
+export const graphQLEndpoint = (() => {
+  try {
+    const graphQLEndpoint = new URL(clientFactoryConfig.endpoint);
+    // GraphQL endpoint URL (Edge endpoint for production and GraphQL Sitecore CM endpoint for dev)
+    const graphQLEndpointUrl = `${graphQLEndpoint.protocol}//${graphQLEndpoint.hostname}`;
+    // Sitecore Edge Context ID - will only be present for production
+    const sitecoreEdgeContextId = graphQLEndpoint.searchParams.get('sitecoreContextId');
+    // Browser request path to the proxy. Includes only the pathname.
+    const pathname = graphQLEndpoint.pathname;
+    // Target URL for the proxy. Can't include the query string.
+    const target = `${graphQLEndpointUrl}${pathname}`;
+
+    return {
+      target,
+      path: pathname,
+      graphQLEndpointUrl,
+      sitecoreEdgeContextId,
+    };
+  } catch (error) {
+    throw new Error(
+      `ERROR: The serverBundle should export a getClientFactoryConfig function with valid GraphQL endpoint URL returned, current value is ${clientFactoryConfig.endpoint}. ` +
+        'Please check your server bundle.'
+    );
+  }
+})();
+
+const { clientFactory } = serverBundle;
+
+export const config: Config = {
+  /**
+   * The require'd server.bundle.js file from your pre-built SPA app.
+   */
+  serverBundle,
+  /**
+   * Port which will be used when start the proxy
+   */
+  port: process.env.PROXY_PORT || 3000,
+};
+
+export const personalizeConfig: PersonalizeConfig = {
+  // Configuration for your Sitecore Experience Edge endpoint
+  edgeConfig: {
+    clientFactory,
+    timeout:
+      (process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT &&
+        parseInt(process.env.PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT)) ||
+      400,
+  },
+  // Configuration for your Sitecore CDP endpoint
+  // Edge URL and ID can be taken from proxy env, or the base SPA app
+  cdpConfig: {
+    sitecoreEdgeUrl: graphQLEndpoint.graphQLEndpointUrl,
+    sitecoreEdgeContextId: graphQLEndpoint.sitecoreEdgeContextId || '',
+    timeout:
+      (process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT &&
+        parseInt(process.env.PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT)) ||
+      400,
+  },
+  // Optional Sitecore Personalize scope identifier.
+  scope: process.env.PERSONALIZE_SCOPE,
+  // This function determines if the personalization should be turned off.
+  // IMPORTANT: You should implement based on your cookie consent management solution of choice.
+  // You may wish to keep it disabled while in development mode.
+  // Personalization will also be disabled when edge context id is missing
+  disabled: () => process.env.NODE_ENV === 'development' || !graphQLEndpoint.sitecoreEdgeContextId,
+  // This function determines if a route should be excluded from personalization.
+  excludeRoute: () => false,
+  sitecoreSiteName: serverBundle.sitecoreSiteName || '',
+  // defaultLanguage will be used as fallback for personalization, if language cannot be read from layout service data
+  defaultLanguage: serverBundle.defaultLanguage,
+};

package/dist/templates/node-xmcloud-proxy/src/index.ts

@@ -0,0 +1,199 @@
+import 'dotenv/config';
+import express, { Response } from 'express';
+import compression from 'compression';
+import { createProxyMiddleware, fixRequestBody } from 'http-proxy-middleware';
+import { debug } from '@sitecore-jss/sitecore-jss';
+import { editingRouter, healthCheck } from '@sitecore-jss/sitecore-jss-proxy';
+import { config, graphQLEndpoint } from './config';
+import { personalizeHelper, personalizePlugin } from './personalize';
+
+const server = express();
+
+const {
+  renderView,
+  parseRouteUrl,
+  dictionaryServiceFactory,
+  layoutServiceFactory,
+} = config.serverBundle;
+
+/**
+ * Required server bundle properties
+ */
+const requiredProperties = [
+  'renderView',
+  'parseRouteUrl',
+  'clientFactory',
+  'getClientFactoryConfig',
+  'defaultLanguage',
+  'layoutServiceFactory',
+  'dictionaryServiceFactory',
+  'components',
+  'metadata',
+];
+
+const missingProperties = requiredProperties.filter((property) => !config.serverBundle[property]);
+
+if (missingProperties.length > 0) {
+  throw new Error(
+    `ERROR: The serverBundle should export the following properties: ${missingProperties.join(
+      ', '
+    )}. Please check your server bundle.`
+  );
+}
+
+const layoutService = layoutServiceFactory.create();
+
+const dictionaryService = dictionaryServiceFactory.create();
+
+/**
+ * Parse requested url in order to detect current route and language
+ * @param {string} reqRoute requested route
+ */
+const getRouteParams = (reqRoute: string) => {
+  const routeParams = parseRouteUrl(reqRoute);
+  let lang;
+  let route;
+
+  if (routeParams) {
+    route = routeParams.sitecoreRoute || '/';
+
+    if (!route.startsWith('/')) {
+      route = `/${route}`;
+    }
+
+    lang = routeParams.lang || '';
+  }
+
+  return { route, lang };
+};
+
+/**
+ * Handle unexpected error
+ * @param {Response} res server response
+ * @param {Error} err error
+ */
+const handleError = (res: Response, err: unknown) => {
+  debug.proxy('response error %o', err);
+
+  res.status(500).send('Internal Server Error');
+};
+
+// enable gzip compression for appropriate file types
+server.use(compression());
+// enable access to req.body
+server.use(graphQLEndpoint.path, express.json());
+
+// turn off x-powered-by http header
+server.settings['x-powered-by'] = false;
+
+// Serve static app assets from local /dist folder
+server.use(
+  '/dist',
+  express.static('dist', {
+    fallthrough: false, // force 404 for unknown assets under /dist
+  })
+);
+
+/**
+ * Proxy browser GraphQL requests to the Sitecore GraphQL endpoint
+ */
+server.use(
+  graphQLEndpoint.path,
+  createProxyMiddleware({
+    target: graphQLEndpoint.target,
+    changeOrigin: true,
+    selfHandleResponse: true,
+    on: {
+      proxyReq: fixRequestBody,
+    },
+    // for client-side routing, personalization is performed by modifying layout service response
+    plugins: [personalizePlugin],
+  })
+);
+
+/**
+ * The health check endpoint
+ */
+server.use(healthCheck());
+
+/**
+ * Proxy editing requests through the editing router
+ */
+server.use(
+  '/api/editing',
+  editingRouter({
+    config: {
+      components: config.serverBundle.components,
+      metadata: config.serverBundle.metadata,
+    },
+    render: {
+      clientFactory: config.serverBundle.clientFactory,
+      renderView,
+    },
+  })
+);
+
+server.use(async (req, res) => {
+  debug.proxy(`performing SSR for ${req.originalUrl}`);
+
+  try {
+    const { route, lang } = getRouteParams(req.originalUrl);
+
+    if (!route) {
+      debug.proxy('no route detected, returning 404');
+
+      res.sendStatus(404);
+
+      return;
+    }
+
+    // Language is required. In case it's not specified in the requested URL, fallback to the default language from the app configuration.
+    let layoutData = await layoutService.fetchLayoutData(
+      route,
+      lang || config.serverBundle.defaultLanguage
+    );
+    // for SSR loading routing, personalization is performed by modifying layoutData directly
+    const personalizedLayoutData = await personalizeHelper.personalizeLayoutData(
+      req,
+      res,
+      layoutData
+    );
+    layoutData = personalizedLayoutData;
+    const viewBag = { dictionary: {} };
+
+    viewBag.dictionary = await dictionaryService.fetchDictionaryData(
+      layoutData.sitecore.context.language || config.serverBundle.defaultLanguage
+    );
+
+    renderView(
+      (err, result) => {
+        if (err) {
+          handleError(res, err);
+          return;
+        }
+
+        if (!result) {
+          debug.proxy('no result returned from renderView, returning 204');
+
+          res.status(204).send();
+          return;
+        }
+
+        const statusCode = layoutData.sitecore.route ? 200 : 404;
+
+        debug.proxy('sending response with status %s', statusCode);
+
+        res.status(statusCode).send(result.html);
+      },
+      route,
+      layoutData,
+      viewBag
+    );
+  } catch (err) {
+    handleError(res, err);
+  }
+});
+
+server.listen(config.port, () => {
+  console.log(`server listening on port ${config.port}!`);
+});

package/dist/templates/node-xmcloud-proxy/src/personalize.ts

@@ -0,0 +1,34 @@
+import { GRAPHQL_LAYOUT_QUERY_NAME, PersonalizeHelper } from '@sitecore-jss/sitecore-jss-proxy';
+import { personalizeConfig } from './config';
+import { responseInterceptor } from 'http-proxy-middleware';
+import { Plugin } from 'http-proxy-middleware/dist/types';
+import { IncomingMessageWithBody } from './types';
+
+export const personalizeHelper = new PersonalizeHelper(personalizeConfig);
+
+// personalize plugin to modify intercepted Layout Service request data
+export const personalizePlugin: Plugin = (proxyServer) => {
+  proxyServer.on(
+    'proxyRes',
+    responseInterceptor(async (responseBuffer, _, req, res) => {
+      let responseText = responseBuffer.toString('utf8');
+      const payload = JSON.stringify((req as IncomingMessageWithBody).body);
+
+      // only apply personalization onto JSS layout service results
+      if (payload.includes(GRAPHQL_LAYOUT_QUERY_NAME)) {
+        let layoutDataRaw = JSON.parse(responseText);
+        if (!layoutDataRaw?.data?.layout?.item?.rendered?.sitecore) {
+          return responseText;
+        }
+        const personalizedLayout = await personalizeHelper.personalizeLayoutData(
+          req as IncomingMessageWithBody,
+          res,
+          layoutDataRaw?.data?.layout?.item?.rendered
+        );
+        layoutDataRaw.data.layout.item.rendered = personalizedLayout;
+        responseText = JSON.stringify(layoutDataRaw);
+      }
+      return responseText;
+    })
+  );
+};

package/dist/templates/node-xmcloud-proxy/src/types.ts

@@ -0,0 +1,37 @@
+/* eslint-disable no-unused-vars */
+import {
+  GraphQLRequestClientFactory,
+  GraphQLRequestClientFactoryConfig,
+} from '@sitecore-jss/sitecore-jss';
+import { DictionaryService } from '@sitecore-jss/sitecore-jss/i18n';
+import { Metadata } from '@sitecore-jss/sitecore-jss/utils';
+import { LayoutService } from '@sitecore-jss/sitecore-jss/layout';
+import { AppRenderer, RouteUrlParser } from '@sitecore-jss/sitecore-jss-proxy';
+import { IncomingMessage } from 'http';
+
+export interface ServerBundle {
+  [key: string]: unknown;
+  renderView: AppRenderer;
+  parseRouteUrl: RouteUrlParser;
+  clientFactory: GraphQLRequestClientFactory;
+  getClientFactoryConfig: () => GraphQLRequestClientFactoryConfig;
+  defaultLanguage: string;
+  sitecoreSiteName: string;
+  layoutServiceFactory: { create: () => LayoutService };
+  dictionaryServiceFactory: { create: () => DictionaryService };
+  components: string[] | Map<string, unknown>;
+  metadata: Metadata;
+}
+
+export interface Config {
+  [key: string]: unknown;
+  port: string | number;
+  serverBundle: ServerBundle;
+}
+
+/**
+ * IncomingMessage type modified with exporess.json() call to include request body
+ */
+export type IncomingMessageWithBody = IncomingMessage & {
+  body: ReadableStream<Uint8Array> | null;
+};

package/dist/templates/node-xmcloud-proxy/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "newLine": "LF",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "noFallthroughCasesInSwitch": true,
+    "rootDir": ".",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "strictFunctionTypes": false,
+    "downlevelIteration": true,
+    "moduleResolution": "node",
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/react/.prettierrc

@@ -1,9 +1,9 @@
-{
-  "endOfLine": "crlf",
-  "semi": true,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "useTabs": false,
-  "trailingComma": "es5",
-  "printWidth": 100
-}
+{
+  "endOfLine": "crlf",
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "printWidth": 100
+}