diff --git a/docs/concepts/search-engine-optimization.md b/docs/concepts/search-engine-optimization.md index 7948cdb4a4..e62f45b605 100644 --- a/docs/concepts/search-engine-optimization.md +++ b/docs/concepts/search-engine-optimization.md @@ -31,7 +31,8 @@ To use a custom `robots.txt`, place it as a file in the `dist` folder. ## Page Metadata -The PWA uses the [Meta service](https://angular.io/api/platform-browser/Meta) for setting tags for title, meta description, robots, canonical links, and open graph infos in page headers. +The PWA uses the [Meta service](https://angular.io/api/platform-browser/Meta) for setting tags for title, meta description, robots, canonical links, and open graph information in the page headers. +For the resource descriptions meta data we use the [Open Graph protocol](https://ogp.me/). Meta information can be added to the routing in form of the data property `meta`. Have a look at [`app-routing.module`](../../src/app/pages/app-routing.module.ts) for examples. diff --git a/docs/guides/customizations.md b/docs/guides/customizations.md index bf5a36db9f..1dad39ce73 100644 --- a/docs/guides/customizations.md +++ b/docs/guides/customizations.md @@ -16,7 +16,10 @@ Generally speaking: It can be tempting to always modify existing templates, component and style files inline when doing customization. However, when merging incoming upgrades the number of merge conflicts can possibly be large. -So if you want to upgrade to new PWA versions later, stick to the following recommendations. +So if you want to upgrade to new PWA versions later, stick to the recommendations in this guide. + +If modifications to standard files seem absolutely inevitable it is good practice to mark the customizations with some `// CUSTOMIZATION` or `` comments. +Either to mark a changed line or as a beginning and end marker for added blocks. ## Set up an Intershop PWA-based Project @@ -66,6 +69,17 @@ CREATE src/app/shared/components/basket/custom-basket-display/custom-basket-disp ... ``` +> [!NOTE] +> The Intershop PWA project is configured to work by default against a publicly available Intershop Commerce Management server (see `environment.model.ts`). +> +> ``` +> icmBaseURL: 'https://pwa-ish-demo.test.intershop.com', +> ``` +> +> To configure your PWA project to use an own default ICM server set the `icmBaseURL` in your projects `environment.model.ts` accordingly. +> +> In the same way the default `icmChannel` configurations need to be adapted in your theme specific `environment..ts` files. + ## Specific Concerns ### Components diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 557696cda7..98c0b15b82 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -12,37 +12,87 @@ kb_sync_latest_only Before working with this project, download and install [Node.js](https://nodejs.org) with the included npm package manager. Currently Node.js 18.16.0 LTS with the corresponding npm 9.5.1 is used for development. -After having cloned the project from the Git repository, open a command line in the project folder and run `npm install`. - -The project uses Angular CLI which has to be installed globally. +The project uses [Angular CLI](https://angular.io/cli) which has to be installed globally. Run `npm install -g @angular/cli` once to globally install Angular CLI on your development machine. -Use `ng serve --open` to start up the development server and open the Progressive Web App in your browser. +### Step 1 - Clone the Project + +```bash +git clone https://github.com/intershop/intershop-pwa.git +``` + +### Step 2 - Install the Dependencies + +After having cloned the project from the Git repository, change into the project folder and run: + +```bash +npm install +``` + +### Step 3 - Start the Intershop PWA + +To start the development server (meaning that changes to the projects source code will automatically be build and reloaded) and open the Intershop PWA in your browser run: + +```bash +ng serve --open +``` + +> [!NOTE] +> The project is configured to work by default against a publicly available Intershop Commerce Management server (see `environment.model.ts`). +> +> ``` +> icmBaseURL: 'https://pwa-ish-demo.test.intershop.com', +> ``` +> +> To run your PWA against an own ICM server configure the `icmBaseURL` in your local `environment.development.ts` or set the `icmBaseURL` in your projects `environment.model.ts` to your own ICM default server. +> +> In the same way the default `icmChannel` configuration needs to be adapted if your own ICM with your own organization should be used. -For more information about environment configuration, server and tools consult the according chapters in the [Development Guide](./development.md). +For more information about the development environment configuration, server and tools consult the according chapters in the [Development Guide](./development.md). + +To simply build and start the Intershop PWA with Server Side Rendering for testing but without the automatic building and reloading of code changes `npm start` works as well and does not require Angular CLI to be installed. ## Customization -Before customizing the PWA for your specific needs, have a look at our [Customization Guide](./customizations.md) and also have a look at the current [PWA Guide](https://support.intershop.de/kb/index.php?c=Search&qoff=0&qtext=guide+progressive+web+app) first. +When starting your own project based on the Intershop PWA that includes customizing the PWA for your specific needs, have a look at our [Customization Guide](./customizations.md) first. ## Deployment -Deployments are generated to the _dist_ folder of the project. +For production and production like deployments we provide an [Intershop PWA Helm Chart](https://github.com/intershop/helm-charts/tree/main/charts/pwa) for Kubernetes deployments. + +> [!NOTE] +> For a Helm chart deployment the configuration property `upstream.icmBaseURL` is a required parameter that should point to your own ICM server. +> +> ```yaml +> upstream: +> icmBaseURL: https://pwa-ish-demo.test.intershop.com +> ``` + +For a simple production like development or testing deployment of the current project state the project includes a `docker-compose.yml` that can be deployed with `docker compose up --build` in the project root. +This will deploy both containers of the Intershop PWA - the pwa (SSR) container as well as the nginx container. + +> [!NOTE] +> For the docker compose deployment an own ICM server can be configured with: +> +> ```yaml +> services: +> pwa: +> environment: +> ICM_BASE_URL: 'https://pwa-ish-demo.test.intershop.com' +> ``` + +You can also manually build the docker image supplied with the `Dockerfile` in the root folder of the project. +Build it with `docker build -t my_pwa .`. +To run the PWA with multiple channels you can use the nginx docker image supplied in the sub folder [nginx](../../nginx). +In general the deployment artifacts of the Intershop PWA are generated to the _dist_ folder of the project. Use `npm run build` to generate an Angular Universal enabled version. On the server the _dist/server.js_ script has to be executed with `node`. - Alternatively, you can use `npm run build client` to get an application using browser rendering. All the files under `dist/browser` have to be served statically. The server has to be configured for fallback routing, see [Server Configuration in Angular Docs](https://angular.io/guide/deployment#server-configuration). -For a production setup we recommend building the docker image supplied with the `Dockerfile` in the root folder of the project. -Build it with `docker build -t my_pwa .`. -To run the PWA with multiple channels you can use the nginx docker image supplied in the sub folder [nginx](../../nginx). - -We provide [Helm Charts](https://github.com/intershop/helm-charts/tree/main/charts/pwa) for Kubernetes deployments. - ## Running Tests Run `npm test` to start an on the fly test running environment to execute the unit tests via [Jest](https://jestjs.io/) once.