Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[template/angular-xmcloud][template/xmcloud-proxy] Add README.md #1965

Merged
merged 12 commits into from
Nov 15, 2024
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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

Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Angular for XMCloud

> Sitecore JSS Angular App for XM Cloud.

[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 / envoy proxy

- Pages new editing integration via HTTP render engine endpoint (e.g. editing/render)

- XMCloud proxy personalization

- Forms support

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:

- `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.
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved

- `XMCloud Proxy`: Adds integration with XMCloud for the JSS SPA applications. Considered experimental.
addy-pathania marked this conversation as resolved.
Show resolved Hide resolved
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved

## Environment Variables
addy-pathania marked this conversation as resolved.
Show resolved Hide resolved

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 `..\\node-xmcloud-proxy\\dist`.
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved
| `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.
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved
| `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://<xmc_cm_host>.sitecorecloud.io. |
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved
| `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 <xmc_cm_host>/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 <xmc_cm_host>/sitecore/api/graph/edge , and it will override any value set in your .env file. Default value `/sitecore/api/graph/edge` |
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved
| `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` |
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved
| `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` 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!`.
Original file line number Diff line number Diff line change
@@ -4,15 +4,21 @@

[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 / envoy proxy

- Pages new editing integration via HTTP render engine endpoint (e.g. editing/render)

- XMCloud proxy personalization

1. Build your SPA app bundle with `jss build`. The build output should be placed in the `dist` folder.
- Forms support

## Setup
## Configuration Setup

Open `config.js` and specify your application settings.
art-alexeyenko marked this conversation as resolved.
Show resolved Hide resolved

@@ -24,13 +30,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*, 'sitecore-jss:layout','sitecore-jss:personalize' to see all logs.

## Pre-requisites

1. SPA sample supports XM Cloud out of the box.
addy-pathania marked this conversation as resolved.
Show resolved Hide resolved

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