This repository contains the code of the frontend application of the IO Public Administrations onboarding portal.

More informations can be found on the IO project website.

• Bash or GitBash
• Docker
• Docker Compose

The application needs to call the REST API provided by the IO onboarding portal backend: to test the frontend locally, you need to start the backend by running its docker-compose stack first. See the backend manual for futher instructions.

See the env.example file for a list of common settings.

The table below describes all the Environment variables needed by the front end of the application.

The frontend container needs to adapt to different environments, reading at run-time environment variables values. For example, the application needs to know the address of the backend application. This is a non trivial task, since Javascript code runs on the client machine of the user executing the application, which prevents the application from directly reading the environment variables from the container.

To overcome this limitation, an env.sh bash script inside scripts folder is executed every time the frontend application container starts. The script reads the environment variables and produces an env-config.js file that is then automatically copied together with the rest of the files to be served by the webserver. The index.html file (in the public folder of this repository) links already to env-config.js, which is read every time the user opens the application in a browser.

IMPORTANT: The env.sh script reads and automatically injects in env-config.js all environment variables prefixed with IO_ONBOARDING_PA, for example IO_ONBOARDING_PA_API_HOST.

To read the variable values inside the frontend application, use the getConfig() method.

The frontend docker image is deployed in production on top of a Kubernetes cluster.

For more informations about IO production deployments and helm-charts, see io-infrastructure-post-config repository.

Currently an Azure development pipeline is configured in order to deploy the master branch of this repository into the IO infrastructure staging environment; the process is triggered by every push into master.

The deployed frontend is reachable at https://pa-onboarding.dev.io.italia.it/.

Set up your environment variables first:

cp env.example .env
# edit .env file

To run the frontend application locally, prepare the environment first:

chmod +x ./scripts/yarn.sh
# launch the docker NodeJS image 
# and run yarn inside the docker container
./scripts/yarn.sh install
./scripts/yarn.sh generate

# run docker-compose up
yarn dev:docker

Point your browser to

• http:https://localhost:1234 for the frontend
• http:https://localhost:3000 to reach the mocked backend

The project uses the json-server package to mock the REST API.

If you run a suitable environment (ie. a Linux machine with NodeJS and yarn installed), you can avoid using docker and run the frontend application directly:

yarn install
yarn generate
yarn dev:local

For multi-language support the application uses:

• react-i18next for the integration of translations with user preferences
• i18next-browser-languageDetector to automatically detect user language
• YAML files in the directory locales
• A YAML-to-typescript conversion script (generate:locales).

To add a new language you must:

1. Create a new directory under locales using the language code as the name (e.g. es for Spanish, de for German, etc...).
2. Copy the content from the base language (en).
3. Proceed with the translation by editing the YAML and eventual Markdown files.
4. Run the Typescript code generation script (yarn generate:locales).
5. New languages will be automatically used if detected as user languages by LanguageDetector used in src/i18n.ts
6. Where user language should be detected and order used in searching is defined by order array in languageDetectorOptions in the same file