Skip to content

Commit

Permalink
[template/angular-xmcloud][template/xmcloud-proxy] Add README.md (#1965)
Browse files Browse the repository at this point in the history 
Co-authored-by: Addy Pathania <[email protected]>
  • Loading branch information
@addy-pathania @apathania22
addy-pathania and apathania22 authored Nov 15, 2024
1 parent 80aab2e commit ff6900f
Show file tree
Hide file tree
Showing 3 changed files with 162 additions and 12 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,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.1

Expand Down
55 changes: 55 additions & 0 deletions packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Angular for XMCloud

> Sitecore JSS Angular App for XM Cloud. For the current release this feature is experimental.
[Documentation](<TODO>)

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.

- `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.

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.

## Components and Supporting Applications

The following components and supporting applications have been added to the Angular base app to ensure compatibility with XM Cloud:

- `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).

- `XM Cloud Proxy`: Adds integration with XMCloud for the JSS SPA applications and enables editing, personalization and A/B component testing support.

## 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. 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`.
| `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 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://<xmc_cm_host>.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 <xmc_cm_host>/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. 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.

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!`.
118 changes: 106 additions & 12 deletions packages/create-sitecore-jss/src/templates/node-xmcloud-proxy/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,129 @@

> Sitecore JSS Proxy for XM Cloud is considered experimental.
[Documentation](<TODO>)
[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.

## Pre-requisites
## Features Supported

1. SPA sample supports XM Cloud out of the box.
- `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:

1. Build your SPA app bundle with `jss build`. The build output should be placed in the `dist` folder.
- 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.

## Setup
- Port Configuration:

Open `config.js` and specify your application settings.
- 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*' 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. |

## 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!`.

## 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`

0 comments on commit ff6900f

Please sign in to comment.