eehitus-document-ui

E-Ehitus document-UI is the main library for showing different documents and document process interactions inside eehitus-ui.

Table of Contents

• Getting started with development
  • Prerequisites
  • Setting local environment variables
  • Running locally
  • Local development
• Development patterns overview
  • Common components
  • Form validation
  • Translations
  • API requests
  • Testing
  • Debugging with source-maps
  • Branching
• How to section start
  • How to setup local env for Windows
  • How to setup local env for Mac
  • How to setup local env for Linux
  • BIM tokens generation instructions

Getting started with development

Prerequisites

• Node.js (v18.20.6)
• Yarn (v1.x)

• Recommendation:
  • Node version manager
  • Node version manager for Windows

Setting local environment variables

• BIM_NPM_TOKEN

• TEHIK_COMP_TOKEN

• How to setup local env for Windows

• How to setup local env for Mac

• How to setup local env for Linux

You can get the token from rancher: Rancher Development tokens

NB! Token should never be commited into the codebase.

Running locally

Follow these steps:

• Create .npmrc file in root of project

Template file location: ./config/.npmrc-template

• You can run terminal command in root project folder:

  cp ./config/.npmrc-template ./.npmrc

• For when running Windows Command Promt(cmd)

  copy config\.npmrc-template .npmrc

If you have setup the env variables and created the .npmrc file run next commands:

• npm i yarn -g - If you don't have yarn installed locally for given node version
• yarn install
• yarn start

Local development

yarn start opens http://localhost:3000

You have to look for BrowserRouter definition to find the urls you can navigate to. Usually can be found at ./src/App.tsx or in the component rendered inside it.

• ./public/config.js contains all the endpoint URL-s for different microservices.
  • Default endpoint should end with /v1
  • You can specify a certain API to point to your projects API /project_ingress
  • handle request proxying in src/setupProxy.cjs
    • to override default proxy routing rules read the instructions in setupProxy.cjs

Development patterns overview

Common components

• eehitus-ui-extras
  • New common business logic components or enums, should be added to this library
• TEDI library - E-Ehitus is moving to use Estonian TEDI library for react.
  • New features should be developed using them, if possible.
• ehr-components Old components
  • These are old components and you should not create new functionality with them if possible.
• eehitus-visuaal eehitus-ui has usage of global styles
  • When making changes there, make sure your change does not have impact to the rest of the UI libraries

Form validation

For form validation we use Yup.

If you have not used it before look find examples used in eehitus-document-ui.

For an Example find usage of: useYupValidation

Translations

All the translations exist in ./src/translations

Webpack at build time merges all the translations into 3 specific files:

• example_project_name_et.json
• example_project_name_en.json
• example_project_name_ru.json

To add new translation files under ./src/translations

Follow that the file ends with *_et.json pattern

API requests

We use axios and we generate the entire API interface for all service requests using OpenApi Generator.

The API clients are located in ./src/services

Generating API with OpenApi Generator

openapi-generator version = 6.6.0

version 6 is required for axios 0.x

$ npm install -g @openapitools/openapi-generator-cli

$ openapi-generator-cli version-manager set 6

If backend is running and openapi doc is accessible (change the port to your matching BE running port)

$ openapi-generator-cli generate -i  http://localhost:9000/v3/api-docs -g typescript-axios --additional-properties=modelPropertyNaming=original --type-mappings=DateTime=Date --type-mappings=object=any

If you need to update service clients with master yaml

• Find the yaml in Gitlab swagger project and download it
• Create a new folder
• Open terminal in the same folder with the yaml

$ openapi-generator-cli generate -i rename-this-to-your-file.yaml -g typescript-axios --additional-properties=modelPropertyNaming=original --type-mappings=DateTime=Date --type-mappings=object=any

• Copy the .ts files into your projects ./src/services/you-api folder

Testing

For library unit testing we use Jest.

E2E Tests are located in this project.

Debugging with source-maps

If you have developed locally and when you update the library version in eehitus-ui project and start receiving errors, it's wise to generate local build using yarn cibuild:debug

This generates ./dist folder

Then go into eehitus-ui project

• Remove .cache eehitus-ui/node_modules/.cache
• Remove old dist eehitus-ui/node_modules/eehitus-*project_name*/dist
• Copy your project local debug build dist folder to eehitus-ui/node_modules/eehitus-*project_name*
• Start eehitus-ui using yarn start now the error should have source-maps and debugging it, should be easier.

Branching

For developing we use Git Flow branching pattern

Example branch names

• release/project_name
• fix/TICKET_NR-short-description
• feature/TICKET_NR-short-description
• company_name/feature/TICKET_NR-short-description

We don't recommend creating develop branch.

Good approach is to create a release/* branch and all new development in company_name/feature/* you create a Merge Request against release/*

You create tags on the release/* branch and you have a separate project namespace in rancher where you update eehitus-ui

Publishing

To get new version of the library up.

1. Go to Gitlab
2. Find your project and go to tags page document-ui as example
3. Create a New tag, specify version in semver pattern version-*.*.* add a description of project tag or other description
4. Update your projects eehitus-ui/package.json version and run yarn to generate new yarn.lock file and commit it
5. Create a New tag for eehitus-ui
6. Update the eehitus-ui in rancher project_namespace, you should never update the v1 ingress eehitus-ui. v1 represents master and should always be in stable state.

How to section start

How to setup local env for Windows

Using System Properties (GUI)

1. Open the Start Menu, search for Environment Variables, and select Edit the system environment variables.
2. In the System Properties window, click on Environment Variables.
3. Under User variables (for the current user) or System variables (for all users), click New or Edit.
4. Enter the variable name and value.
5. Click OK, then Apply.
6. Restart the terminal or log out and log back in to apply the changes.

Using Command Prompt (For Current and Future Sessions)

setx VAR_NAME "VALUE"

This sets the variable permanently for the current user.

To verify:

echo %VAR_NAME%

Using PowerShell

[System.Environment]::SetEnvironmentVariable("VAR_NAME", "VALUE", "User")

Replace User with Machine to set for all users.

How to setup local env for Mac

Using .zshrc (For Zsh, Default Shell in macOS 10.15+)

1. Open Terminal.
2. Edit the .zshrc file:

   nano ~/.zshrc

3. Add the following line:

   export VAR_NAME="VALUE"

4. Save and exit (CTRL+X, then Y, then ENTER).
5. Apply the changes:

   source ~/.zshrc

6. Verify:

   echo $VAR_NAME

Using .bash_profile (For Bash, Older macOS Versions)

Follow the same steps but edit ~/.bash_profile instead of ~/.zshrc.

How to setup local env for Linux

Using .bashrc or .bash_profile

1. Open Terminal.
2. Edit the shell configuration file:

   nano ~/.bashrc  # or ~/.bash_profile

3. Add the following line:

   export VAR_NAME="VALUE"

4. Save and exit (CTRL+X, then Y, then ENTER).
5. Apply the changes:

   source ~/.bashrc  # or source ~/.bash_profile

6. Verify:

   echo $VAR_NAME

Using /etc/environment (For System-wide Variables)

1. Open Terminal.
2. Edit the /etc/environment file (requires sudo):

   sudo nano /etc/environment

3. Add the variable:

   VAR_NAME="VALUE"

4. Save and exit.
5. Apply the changes by logging out and logging back in or restarting the system.

BIM tokens generation instructions

https://bimbase.notion.site/JavaScript-NPM-07021426de2c43df826896aa05f097a3