Before working with this project, download and install Node.js with the included npm package manager.
Currently Node.js 14.x LTS with the corresponding npm is required.
After having cloned the project from the Git repository, open a command line in the project folder and run
The project uses Angular CLI which has to be installed globally.
npm install -g @angular/cli once to globally install Angular CLI on your development machine.
ng serve --open to start up the development server and open the Progressive Web App in your browser.
The project can alternatively be run in production mode with
An alternative development setup for the PWA is provided when using Visual Studio Code Remote - Containers to work in an isolated pre-configured project development environment.
After cloning your local working copy (e.g. with VS Code), VSCode will ask you if you want to reopen the folder in a container.
By doing this, VS Code will prepare the environment for you inside the container.
It installs Node.js LTS, Angular CLI and also performs all required setup steps to get you started in an isolated environment.
Open a console in VS Code and run
ng serve to start developing.
ng serve or
ng s for a development server that is configured by default via environment.ts to use mocked responses instead of actual REST calls.
ng serve --configuration=production or
ng s -c production starts a server that will communicate by default with the Intershop Commerce Management of our public demo via REST API.
The project is also configured to support the usage of an own local environment file environment.local.ts that can be configured according to the development environment, e.g. with a different icmBaseURL or different configuration options (see the environment.model.ts).
This file will be ignored by Git so the developer-specific setting will not be committed.
To use this local environment configuration, the server should be started with
ng s -c local.
Multiple configurations can also be combined, where
production should be the last in the list:
ng serve -c local,production.
Once the server is running, navigate to http://localhost:4200/ in your browser to see the application.
The application will automatically reload if you change any of the source files.
ng serve --port 4300 will start the server on a different port than the default 4200 port, e.g., if one wants to run multiple instances in parallel for comparison.
ng serve --open will automatically open a new browser tab with the started application.
The different start options can be combined.
Warning: Do not use webpack-dev-server in production!
Also have a look at further information in the Development Guide
Deployments are generated to the dist folder of the project.
npm run build to generate an Angular Universal enabled version.
On the server the dist/server.js script has to be executed with
Alternatively, you can use
ng build --prod 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.
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 and Google PageSpeed optimizations, you can use the nginx docker image supplied in the sub folder nginx.
To run the project as a Progressive Web App with an enabled Service Worker, use
npm run start to build and serve the application.
After that open http://localhost:4200 in your browser and test it or run a PWA audit.
Currently only localhost or 127.0.0.1 will work with the service worker since it requires https communication on any other domain.
npm test to start an on the fly test running environment to execute the unit tests via Jest once.
To run Jest in watch mode with interactive interface, run
npm run test:watch.
npm run e2e to execute the end-to-end tests via cypress.
You have to start your development or production server first as cypress will instruct you.
Head over to the Testing Concept documentation for more information.
npm run lint to run a static code analysis.
For development make sure the used IDE or editor follows the EditorConfig configuration of the project and uses Prettier to help maintain consistent coding styles (see
npm run format to perform a formatting run on the code base with Prettier.
Learning the TypeScript typing system can be quite hard and it can take years to finally master it, but it also helps to avoid bugs by passing around untyped data.
Typing can be especially tedious when it comes to tests, but there it is as important as in the production code.
If the tests are running successfully on untyped (and sometimes outdated) data, nobody will be the wiser.
Almost everything can be typed correctly without using
If generic typing is not possible, you can use
object for utility functions.
In most other cases, the typings can be correctly applied.
We encourage everybody to up their game about strict typing with TypeScript, but as always, there are ways around it.
We supply a
tsconfig.app-no-checks.json in the source root, that can be used for Angular builders in the
angular.json to disable all safety features.
However, we don't support doing this for production builds.
npm run check is a combination task of
test that runs some of the checks that will also be performed in continuous integration on the whole code base.
Do not overuse it as the run might take a long time.
npx lint-staged to perform a manual quick evaluation of staged files.
This also happens automatically when committing files.
It is also possible to bypass verification on commit, following the suggestions of the versioning control tool of your choice.
With the integrated
intershop-schematics this project provides the functionality to generate different code artifacts according to our style guide and project structure.
ng generate will use our custom schematics by default, e.g. run
ng generate component component-name in the shared folder to generate a new shared component.
ng generate --help gives an overview of available Intershop-specific schematics.
The Angular CLI default schematics are still available and working.
However, they need to be prefixed to use them, e.g.
ng generate @schematics/angular:guard.
A list of the available Angular CLI schematics can be fetched with
ng generate @schematics/angular: --help.
To get more help on the Angular CLI, use
ng help or check out the Angular CLI Documentation.
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.