From 9a37a9daf6a456bd604a83cc9a699fa44b808b07 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Fri, 8 Nov 2024 13:43:48 -0500 Subject: [PATCH 01/10] add readme --- .../src/templates/angular-xmcloud/README.md | 58 +++++++++++++++++++ .../templates/node-xmcloud-proxy/README.md | 28 +++++++-- 2 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md new file mode 100644 index 0000000000..734617975c --- /dev/null +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -0,0 +1,58 @@ +# Angular for XMCloud + +> Sitecore JSS Angular App for XM Cloud. + +[Documentation]() + +This Single Page Application (SPA) built with Angular is designed to be fully compatible with XM Cloud, incorporating several key add-ons and features to streamline the development process and enable seamless integration. The supported key features are as follows: + +- Context ID / envoy proxy + +- Pages new editing integration via HTTP render engine endpoint (e.g. editing/render) + +- Personalization middleware (can do layout manipulation directly since we are always SSR) + +- Rewrites middleware + +- Forms support + +- Multisite + +This SPA is tailored to enhance development workflows and enable full utilization of XM Cloud’s capabilities, providing a seamless and efficient foundation for developers. + +## Add-ons added +Following are the add-ons added to the Angular base app to make it compatible with XM Cloud: + +- `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Also includes example components for SXA projects. + +- `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications. Considered experimental. + +## Environment Variables + +The following environment variables can be set to configure the angular app. 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_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. | +| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the proxy server path. +| `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | +| `SITECORE_API_KEY` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | +| `SITECORE_API_HOST` | The API hostname, needed to build the application. When the application runs on the XM Cloud rendering host, this value is always set to your content management instance, and it will override any value set in your .env file. For example, https://.sitecorecloud.io. | +| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. When the application runs on the XM Cloud rendering host, this value is always set to the preview endpoint for your CM instance /sitecore/api/graph/edge , and it will override any value set in your .env file. | +| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. | +| `DEFAULT_LANGUAGE` | The default language of your app. | +| `FETCH_WITH` | Determines how layout and dictionary data is fetched from Sitecore. The possible values are REST and GraphQL. You select the value during the app scaffold process. If the value isn't provided, the default is GraphQL. | +| `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. + +## Build & run + +Build your Angular SPA app bundle with `jss build`. The build output should be placed in the `dist` folder and will automatically get copied to the proxy app. + +To run your app in production mode. Go to the proxy app: + +1. Run `npm install` + +2. Run `npm run start` + +You should be able to see the following message: +`server listening on port 3000!`. \ No newline at end of file diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index f64f04bf33..44bb5d46d6 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -4,15 +4,25 @@ [Documentation]() +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. -## Pre-requisites +## Features Supported -1. SPA sample supports XM Cloud out of the box. +- Context ID / envoy proxy + +- Pages new editing integration via HTTP render engine endpoint (e.g. editing/render) + +- Personalization middleware (can do layout manipulation directly since we are always SSR) + +- Rewrites middleware -1. Build your SPA app bundle with `jss build`. The build output should be placed in the `dist` folder. +- Forms support -## Setup +- Multisite + +## Configuration Setup Open `config.js` and specify your application settings. @@ -24,13 +34,19 @@ The following environment variables can be set to configure the Proxy sample ins | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `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*' to see all logs. | +| `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' 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`. The build output should be placed in the `dist` folder. | ## Build & run 1. Run `npm install` -1. Run `npm run start` +2. Run `npm run start` You should be able to see the following message: `server listening on port 3000!`. From 4e4cc22a23be82b1011e8c349cdf11e32de49ec2 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Fri, 8 Nov 2024 13:51:57 -0500 Subject: [PATCH 02/10] update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c3f323c1a..09cea4435e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -89,6 +89,7 @@ Our versioning strategy is as follows: * `[templates/angular]``[templates/node-xmcloud-proxy]``[templates/node-headless-ssr-proxy]``[templates/node-headless-ssr-experience-edge]` Adjust out of box .gitignore rules * New Angular add-on's are not scaffolded within build pipeline ([#1962](https://github.com/Sitecore/jss/pull/1962)) +* `[template/angular-xmcloud]``[template/xmcloud-proxy]` Add README.md ([#1965](https://github.com/Sitecore/jss/pull/1965)) ## 22.2.0 From f6b0f67a85669afb8b168caaab13568d17fda39b Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Mon, 11 Nov 2024 12:40:33 -0500 Subject: [PATCH 03/10] refactor readme --- .../src/templates/angular-xmcloud/README.md | 26 ++++++++----------- .../templates/node-xmcloud-proxy/README.md | 10 +++---- 2 files changed, 14 insertions(+), 22 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md index 734617975c..911451f0c7 100644 --- a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -10,18 +10,15 @@ This Single Page Application (SPA) built with Angular is designed to be fully co - Pages new editing integration via HTTP render engine endpoint (e.g. editing/render) -- Personalization middleware (can do layout manipulation directly since we are always SSR) - -- Rewrites middleware +- XMCloud proxy personalization - Forms support -- Multisite - This SPA is tailored to enhance development workflows and enable full utilization of XM Cloud’s capabilities, providing a seamless and efficient foundation for developers. -## Add-ons added -Following are the add-ons added to the Angular base app to make it compatible with XM Cloud: +## Components and Supporting Applications + +The following components and supporting applications have been added to the Angular base app to ensure compatibility with XM Cloud: - `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Also includes example components for SXA projects. @@ -33,20 +30,19 @@ The following environment variables can be set to configure the angular app. You | Parameter | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. | -| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the proxy server path. +| `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. Default value `http://localhost:3000` | +| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `..\\node-xmcloud-proxy\\dist`. | `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | -| `SITECORE_API_KEY` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | +| `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your XM Cloud preview API Key. When the application runs on the XM Cloud rendering host, this value is always set to your Sitecore Services Client API Key, and it will override any value set in your .env file. | `SITECORE_API_HOST` | The API hostname, needed to build the application. When the application runs on the XM Cloud rendering host, this value is always set to your content management instance, and it will override any value set in your .env file. For example, https://.sitecorecloud.io. | -| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. When the application runs on the XM Cloud rendering host, this value is always set to the preview endpoint for your CM instance /sitecore/api/graph/edge , and it will override any value set in your .env file. | -| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. | -| `DEFAULT_LANGUAGE` | The default language of your app. | -| `FETCH_WITH` | Determines how layout and dictionary data is fetched from Sitecore. The possible values are REST and GraphQL. You select the value during the app scaffold process. If the value isn't provided, the default is GraphQL. | +| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. When the application runs on the XM Cloud rendering host, this value is always set to the preview endpoint for your CM instance /sitecore/api/graph/edge , and it will override any value set in your .env file. Default value `/sitecore/api/graph/edge` | +| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `sitecore-jss-angular` | +| `DEFAULT_LANGUAGE` | The default language of your app. Default value `en` | | `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. ## Build & run -Build your Angular SPA app bundle with `jss build`. The build output should be placed in the `dist` folder and will automatically get copied to the proxy app. +Build your Angular SPA app bundle with `jss build` or `npm run build`. The build output should be placed in the `dist` folder and will automatically get copied to the proxy app. To run your app in production mode. Go to the proxy app: diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index 44bb5d46d6..b0bff37d46 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -14,14 +14,10 @@ This is a sample setup showing one of how you can configure XM Cloud rendering s - Pages new editing integration via HTTP render engine endpoint (e.g. editing/render) -- Personalization middleware (can do layout manipulation directly since we are always SSR) - -- Rewrites middleware +- XMCloud proxy personalization - Forms support -- Multisite - ## Configuration Setup Open `config.js` and specify your application settings. @@ -34,13 +30,13 @@ The following environment variables can be set to configure the Proxy sample ins | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `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*' to see all logs. +| `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`. The build output should be placed in the `dist` folder. | +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 From 975bd6a940532e11589fdbddcdb993cc944c741e Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Tue, 12 Nov 2024 16:10:35 -0500 Subject: [PATCH 04/10] add netlify instructions --- .../src/templates/angular-xmcloud/README.md | 13 +++---- .../templates/node-xmcloud-proxy/README.md | 35 +++++++++++++++++++ 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md index 911451f0c7..c958d80675 100644 --- a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -1,6 +1,6 @@ # Angular for XMCloud -> Sitecore JSS Angular App for XM Cloud. +> Sitecore JSS Angular App for XM Cloud is considered experimental. [Documentation]() @@ -20,7 +20,7 @@ This SPA is tailored to enhance development workflows and enable full utilizatio The following components and supporting applications have been added to the Angular base app to ensure compatibility with XM Cloud: -- `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Also includes example components for SXA projects. +- `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Angular app provides components and can be used during development. Once the app is built and its build artifacts are copied into the proxy, the proxy app can be used to connect to an XMCloud instance and render its content (including personalization etc). - `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications. Considered experimental. @@ -31,12 +31,13 @@ The following environment variables can be set to configure the angular app. You | Parameter | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. Default value `http://localhost:3000` | -| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `..\\node-xmcloud-proxy\\dist`. +| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `<%xmcloud_proxy_path%>\dist`. | `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | -| `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your XM Cloud preview API Key. When the application runs on the XM Cloud rendering host, this value is always set to your Sitecore Services Client API Key, and it will override any value set in your .env file. +| `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your XM Cloud preview API Key. | `SITECORE_API_HOST` | The API hostname, needed to build the application. When the application runs on the XM Cloud rendering host, this value is always set to your content management instance, and it will override any value set in your .env file. For example, https://.sitecorecloud.io. | -| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. When the application runs on the XM Cloud rendering host, this value is always set to the preview endpoint for your CM instance /sitecore/api/graph/edge , and it will override any value set in your .env file. Default value `/sitecore/api/graph/edge` | -| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `sitecore-jss-angular` | +| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. | +| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `<%- appName %>`, +` | | `DEFAULT_LANGUAGE` | The default language of your app. Default value `en` | | `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index b0bff37d46..3fc3e9ce12 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -46,3 +46,38 @@ The following environment variables can be set to configure the Proxy sample ins You should be able to see the following message: `server listening on port 3000!`. + +## Deploy to Netlify + +1. All of the netlify configuration is in `netlify.toml` +2. proxy/package.json has extra commands, they ensure build and install steps would work: + +``` + "build-all": "cd ../angular && npm run build && cd ../proxy && tsc", + "install-all": "cd ../angular && npm i && cd ../proxy" +``` +3. <%- appName %>/package.json has its own commands that would be used by netlify: +``` + "build": "cd ./proxy && npm run build-all && cd ..", + "install": "cd ./proxy && npm run install-all && cd ..", + "deploy-netlify": "netlify build && netlify deploy --prod" +``` +4. 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" +``` +5. To ensure that static files under /dist are not accessible via browser add `force=true` +``` + [[redirects]] + from = "/*" + status = 200 + to = "/.netlify/functions/index/:splat" + force = true +``` +6. 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/) +7. Set up environment variables. +8. Set up your build settings in Build and Deploy tab. +9. If proxy/dist folder is not picked up properly by Netlify make sure to add env variable in the netlify site where path is unix style path e.g. `../proxy/dist` \ No newline at end of file From 59bbd22007664a6e6193990309d1536157848158 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Tue, 12 Nov 2024 16:22:28 -0500 Subject: [PATCH 05/10] add docs link --- .../src/templates/angular-xmcloud/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md index c958d80675..2242ea6cf3 100644 --- a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -39,11 +39,11 @@ The following environment variables can be set to configure the angular app. You | `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `<%- appName %>`, ` | | `DEFAULT_LANGUAGE` | The default language of your app. Default value `en` | -| `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. +| `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. Refer to the [official docs](https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-headless-development/debug-logging-in-jss-apps.html#namespaces) for all the available namespaces. ## Build & run -Build your Angular SPA app bundle with `jss build` or `npm run build`. The build output should be placed in the `dist` folder and will automatically get copied to the proxy app. +Build your Angular SPA app bundle with `jss build` or `npm run build`. The build output should be placed in the `dist` folder and will automatically get copied to the proxy app. To run your app in production mode. Go to the proxy app: From db6c2c17ba79494db440423e1b1e01987f5ca6d1 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Tue, 12 Nov 2024 16:33:33 -0500 Subject: [PATCH 06/10] expand configuration content --- .../templates/node-xmcloud-proxy/README.md | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index 3fc3e9ce12..eccf7297a9 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -20,7 +20,32 @@ This is a sample setup showing one of how you can configure XM Cloud rendering s ## Configuration Setup -Open `config.js` and specify your application settings. +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 Controls: Functions to manage personalization based on environment (e.g., disabled in development mode) and consent management solutions. + - Language Configuration: defaultLanguage serves as a fallback if language data is unavailable. + +This configuration is designed to be flexible and secure, with dynamic settings managed via environment variables where appropriate. ### Environment Variables From 9a601850c47c803a7b9f37cc7b4a70f1ead392e2 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Wed, 13 Nov 2024 15:42:13 -0500 Subject: [PATCH 07/10] update readme --- .../src/templates/angular-xmcloud/README.md | 22 +++--- .../templates/node-xmcloud-proxy/README.md | 76 ++++++++++--------- 2 files changed, 53 insertions(+), 45 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md index 2242ea6cf3..8213ba3789 100644 --- a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -1,18 +1,18 @@ # Angular for XMCloud -> Sitecore JSS Angular App for XM Cloud is considered experimental. +> Sitecore JSS Angular App for XM Cloud. For the current release this feature is experimental. [Documentation]() This Single Page Application (SPA) built with Angular is designed to be fully compatible with XM Cloud, incorporating several key add-ons and features to streamline the development process and enable seamless integration. The supported key features are as follows: -- Context ID / envoy proxy +- 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 (e.g. editing/render) +- 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. -- XMCloud proxy personalization +- XMCloud proxy personalization with embedded personalization and A/B component test support. -- Forms 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. This SPA is tailored to enhance development workflows and enable full utilization of XM Cloud’s capabilities, providing a seamless and efficient foundation for developers. @@ -22,7 +22,7 @@ The following components and supporting applications have been added to the Angu - `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Angular app provides components and can be used during development. Once the app is built and its build artifacts are copied into the proxy, the proxy app can be used to connect to an XMCloud instance and render its content (including personalization etc). -- `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications. Considered experimental. +- `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications and enables editing, personalization and A/B component testing support. ## Environment Variables @@ -31,12 +31,12 @@ The following environment variables can be set to configure the angular app. You | Parameter | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. Default value `http://localhost:3000` | -| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `<%xmcloud_proxy_path%>\dist`. +| `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `\dist`. | `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | -| `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your XM Cloud preview API Key. -| `SITECORE_API_HOST` | The API hostname, needed to build the application. When the application runs on the XM Cloud rendering host, this value is always set to your content management instance, and it will override any value set in your .env file. For example, https://.sitecorecloud.io. | -| `GRAPH_QL_ENDPOINT` | The GraphQL endpoint. For Experience Edge, the value is https://edge.sitecorecloud.io/api/graphql/v1. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. | -| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `<%- appName %>`, +| `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your preview API Key from the CM instance. +| `SITECORE_API_HOST` | The API hostname, needed to build the application. This should be used in combination with SITECORE_API_KEY for local development or local container setup. For example, https://.sitecorecloud.io. | +| `GRAPH_QL_ENDPOINT` | Your GraphQL Edge endpoint. This is typically optional. By default, the endpoint is calculated using the resolved Sitecore API hostname + the `graphQLEndpointPath` defined in your `package.json`. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is /sitecore/api/graph/edge. | +| `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value ``, ` | | `DEFAULT_LANGUAGE` | The default language of your app. Default value `en` | | `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. Refer to the [official docs](https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-headless-development/debug-logging-in-jss-apps.html#namespaces) for all the available namespaces. diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index eccf7297a9..febc7cdf24 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -42,8 +42,8 @@ The config.ts file in this proxy app handles essential configurations for server * 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 Controls: Functions to manage personalization based on environment (e.g., disabled in development mode) and consent management solutions. - - Language Configuration: defaultLanguage serves as a fallback if language data is unavailable. + - 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. @@ -74,35 +74,43 @@ You should be able to see the following message: ## Deploy to Netlify -1. All of the netlify configuration is in `netlify.toml` -2. proxy/package.json has extra commands, they ensure build and install steps would work: - -``` - "build-all": "cd ../angular && npm run build && cd ../proxy && tsc", - "install-all": "cd ../angular && npm i && cd ../proxy" -``` -3. <%- appName %>/package.json has its own commands that would be used by netlify: -``` - "build": "cd ./proxy && npm run build-all && cd ..", - "install": "cd ./proxy && npm run install-all && cd ..", - "deploy-netlify": "netlify build && netlify deploy --prod" -``` -4. 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" -``` -5. To ensure that static files under /dist are not accessible via browser add `force=true` -``` - [[redirects]] - from = "/*" - status = 200 - to = "/.netlify/functions/index/:splat" - force = true -``` -6. 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/) -7. Set up environment variables. -8. Set up your build settings in Build and Deploy tab. -9. If proxy/dist folder is not picked up properly by Netlify make sure to add env variable in the netlify site where path is unix style path e.g. `../proxy/dist` \ No newline at end of file +`NOTE: If you are using the Angular starter from the XM-Cloud-Foundation repository within a monorepo, please skip to Step 4.` + +1. Ensure that your Netlify configuration is specified in `netlify.toml`. If this file does not exist, create it and add the following configuration: + - Following functions lets the proxy app to treated as netlify functions. [Functions Overview](https://docs.netlify.com/functions/overview/) + ``` + [functions] + directory = "proxy/src" + node_bundler = "esbuild" + included_files = ["proxy/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` + ``` + [[redirects]] + from = "/*" + status = 200 + to = "/.netlify/functions/index/:splat" + force = true + ``` +2. Run `npm init` in the root directory and add the following scripts to package.json: + ``` + "build": "cd ./proxy && npm run build-all && cd ..", + "install": "cd ./proxy && npm run install-all && cd ..", + ``` +3. Ensure that proxy/package.json includes the following commands to handle the build and install steps properly:: + + ``` + "build-all": "cd ../angular && npm run build && cd ../proxy && tsc", + "install-all": "cd ../angular && npm i && cd ../proxy" + ``` +4. 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/) +5. Set up environment variables. +6. Set up your build settings in Build and Deploy tab. +7. If proxy/dist folder is not picked up properly by Netlify make sure to add env variable in the netlify site where path is unix style path e.g. `../proxy/dist` \ No newline at end of file From 19875a4e61cf8b78239d0e4fc5d2ceef22fa339a Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Thu, 14 Nov 2024 16:36:52 -0500 Subject: [PATCH 08/10] refactor readme --- .../src/templates/angular-xmcloud/README.md | 12 ++++++------ .../src/templates/node-xmcloud-proxy/README.md | 8 +++----- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md index 8213ba3789..5b608815db 100644 --- a/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md +++ b/packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md @@ -6,13 +6,13 @@ This Single Page Application (SPA) built with Angular is designed to be fully compatible with XM Cloud, incorporating several key add-ons and features to streamline the development process and enable seamless integration. The supported key features are as follows: -- 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. +- `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. +- `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. -- XMCloud proxy personalization with embedded personalization and A/B component test support. +- `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. +- `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. This SPA is tailored to enhance development workflows and enable full utilization of XM Cloud’s capabilities, providing a seamless and efficient foundation for developers. @@ -20,9 +20,9 @@ This SPA is tailored to enhance development workflows and enable full utilizatio The following components and supporting applications have been added to the Angular base app to ensure compatibility with XM Cloud: -- `XMCloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Angular app provides components and can be used during development. Once the app is built and its build artifacts are copied into the proxy, the proxy app can be used to connect to an XMCloud instance and render its content (including personalization etc). +- `XM Cloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Angular app provides components and can be used during development. Once the app is built and its build artifacts are copied into the proxy, the proxy app can be used to connect to an XMCloud instance and render its content (including personalization etc). -- `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications and enables editing, personalization and A/B component testing support. +- `XM Cloud Proxy`: Adds integration with XMCloud for the JSS SPA applications and enables editing, personalization and A/B component testing support. ## Environment Variables diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index febc7cdf24..fb2a3d408b 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -76,7 +76,7 @@ You should be able to see the following message: `NOTE: If you are using the Angular starter from the XM-Cloud-Foundation repository within a monorepo, please skip to Step 4.` -1. Ensure that your Netlify configuration is specified in `netlify.toml`. If this file does not exist, create it and add the following configuration: +1. Ensure that your Netlify configuration is specified in `netlify.toml`. If this file does not exist, create it at the root and add the following configuration: - Following functions lets the proxy app to treated as netlify functions. [Functions Overview](https://docs.netlify.com/functions/overview/) ``` [functions] @@ -91,11 +91,10 @@ You should be able to see the following message: status = 200 to = "/browser/:splat" ``` - - To ensure that static files under /dist are not accessible via browser add `force=true` + - 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 ``` @@ -105,7 +104,6 @@ You should be able to see the following message: "install": "cd ./proxy && npm run install-all && cd ..", ``` 3. Ensure that proxy/package.json includes the following commands to handle the build and install steps properly:: - ``` "build-all": "cd ../angular && npm run build && cd ../proxy && tsc", "install-all": "cd ../angular && npm i && cd ../proxy" From 85b9ef74fa62482f23d55671513cdb538e244f07 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Fri, 15 Nov 2024 14:51:38 -0500 Subject: [PATCH 09/10] add steps for netlify deployement --- .../templates/node-xmcloud-proxy/README.md | 124 ++++++++++-------- 1 file changed, 68 insertions(+), 56 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index fb2a3d408b..baab392f71 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -2,7 +2,7 @@ > Sitecore JSS Proxy for XM Cloud is considered experimental. -[Documentation]() +[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. @@ -10,13 +10,13 @@ This is a sample setup showing one of how you can configure XM Cloud rendering s ## Features Supported -- Context ID / envoy proxy +- `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 (e.g. editing/render) +- `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. -- XMCloud proxy personalization +- `XM Cloud proxy personalization` with embedded personalization and A/B Component Test support. -- Forms 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 @@ -24,26 +24,26 @@ The config.ts file in this proxy app handles essential configurations for server - 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. + - 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. + - 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. + - 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. + - 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. @@ -51,17 +51,17 @@ This configuration is designed to be flexible and secure, with dynamic settings 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. +| 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. | +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 @@ -74,41 +74,53 @@ You should be able to see the following message: ## Deploy to Netlify -`NOTE: If you are using the Angular starter from the XM-Cloud-Foundation repository within a monorepo, please skip to Step 4.` - -1. Ensure that your Netlify configuration is specified in `netlify.toml`. If this file does not exist, create it at the root and add the following configuration: +`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 ./ && npm run build-all && cd ..", + "install": "cd ./ && npm install && npm run install-all && cd ..", + ``` +2. Ensure that `/package.json` includes the following commands to handle the build and install steps properly:: + ``` + "build-all": "cd ../angular && npm run build && cd ../ && tsc", + "install-all": "cd ../angular && npm i && cd ../" + ``` +3. 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 = "proxy/src" - node_bundler = "esbuild" - included_files = ["proxy/dist/**"] - ``` + ``` + [functions] + directory = "/src" + node_bundler = "esbuild" + included_files = ["/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" - ``` + ``` + [[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]] - ... - to = "/.netlify/functions/index/:splat" - force = true - ``` -2. Run `npm init` in the root directory and add the following scripts to package.json: - ``` - "build": "cd ./proxy && npm run build-all && cd ..", - "install": "cd ./proxy && npm run install-all && cd ..", - ``` -3. Ensure that proxy/package.json includes the following commands to handle the build and install steps properly:: - ``` - "build-all": "cd ../angular && npm run build && cd ../proxy && tsc", - "install-all": "cd ../angular && npm i && cd ../proxy" - ``` + ``` + [[redirects]] + from = "/*" + status = 200 + to = "/.netlify/functions/index/:splat" + force = true + ``` + - Build command + ``` + [build] + command = "npm run build" + publish = "/dist" + ``` 4. 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/) -5. Set up environment variables. -6. Set up your build settings in Build and Deploy tab. -7. If proxy/dist folder is not picked up properly by Netlify make sure to add env variable in the netlify site where path is unix style path e.g. `../proxy/dist` \ No newline at end of file + a. Set up all your necessary environment variables. + 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` From ac32fa2348a282fe3b2a22360c76890edfc12d68 Mon Sep 17 00:00:00 2001 From: Addy Pathania Date: Fri, 15 Nov 2024 15:15:48 -0500 Subject: [PATCH 10/10] add extra step --- .../src/templates/node-xmcloud-proxy/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md index baab392f71..c5ca62c2d6 100644 --- a/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md +++ b/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md @@ -86,7 +86,11 @@ You should be able to see the following message: "build-all": "cd ../angular && npm run build && cd ../ && tsc", "install-all": "cd ../angular && npm i && cd ../" ``` -3. Create a `netlfiy.toml` file if not already created and ensure that the following Netlify configuration is added there: +3. Add `serverless-http` to the list of dependencies in `/package.json` and then add the following variable to your ``/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] @@ -115,8 +119,8 @@ You should be able to see the following message: command = "npm run build" publish = "/dist" ``` -4. 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. +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: /