Skip to content

APIHUB Frontend Development Guide

Jump to bottom
b41ex edited this page Mar 18, 2025 · 14 revisions

DRAFT

Main Scenarios

Initial setup

Setup GitHub NPM registry.

Learn how to run APIHUB locally

Learn basic concepts and functionality of APIHUB

  • create private workspace
  • publish package via portal (e.g. publish APIHUB Backend API)
  • publish several versions of package
  • compare packages
  • see BWC analysis for the packages

Build components locally (at least APIHUB UI)

Learn how to run APIHUB UI from local sources using proxy development mode.

Learn how to run Playwright tests on APIHUB Portal (<TBD>).

Learn APIHUB Frontend branching and versioning strategy.

Familiarize yourself with the APIHUB Ticketing Guide

Working on a feature/bugfix

Create a branch from develop, named according to branching conventions. If there are changes required in several dependent components- create branch in each component, according to process described in Cross-cutting feature development

Work on implementation of required functionality/bugfix.

Run unit/screenshot/integration test as described in Testing.

Create a Pull Request to develop, assign to reviewers.

Make sure, you are following git messages conventions for commits and PRs

Iterate on the code to fix issues raised during review.

Branching Strategy

We use a classic Gitflow branching model with minor variations.

Here are the differences:

  • only one release branch named release (we do not have several releases happening simultaneously)
  • only one hotfix branch named hotfix (again, there are no use cases for several hotfixes being prepared simultaneously)
  • topic branches could be named either feature/* or bugfix/*

Regular development and bugfix mainly happens in develop and topic branches (i.e. feature/* or bugfix/*). Make sure you understand flows around those.

Versioning Strategy

We use Semantic Versioning.

Version for a package in a main branch is set to release version (e.g. 2.10.0) during release process.

Versions for packages from development branches will have both release part (e.g. 2.10.1) and pre-release suffix. Base release part in develop branch is assigned by release manager during release. Pre-release suffix is added automatically by CI process during build. You do not need to add or modify pre-release suffix in development branches manually.

When package version is published from some branch, it will have corresponding NPM dist-tag assigned automatically. These should be used to specify dependencies between packages in development branches. See details in Cross-cutting feature development

Branch Version Example NPM Dist Tag
develop 2.10.1-dev.20250317141223 dev
feature/my-feature 2.10.1-feature-my-feature.20250317141223 feature-my-feature
release 2.10.1-next.20250317141223 next
hotfix 2.10.1-hotfix.20250317141223 hotfix

git messages conventions

Use Conventional Commits conventions for commit messages and PR titles.

Running APIHUB locally

There's a Docker Compose file that allows to run APIHUB locally from Docker images.

Release Docker images are published with tags corresponding to version (e.g. 2.9.0) or you could use one of Docker image tags for development branches:

Branch Name Docker Image Tag
develop dev
feature/my-feature feature-my-feature
release next

You can always look-up packages available for the repository in the Packages section, e.g. here are APIHUB UI Docker Images.

Using proxy development mode

It is useful to be able to run UI build from sources locally and connect to some APIHUB instance (it could be cloud instance or it could be APIHUB instance spin up on localhost). You can test and debug your latest changes without rebuilding the UI Docker image.

Running UI in proxy development mode allows to do just that.

  • open vite.config.ts file of the package you want to run (e.g. Portal)
  • specify the instance you want to connect to in proxyServer const (e.g. `http://localhost:8081/)
  • run proxy NPM script from corresponding (e.g. for Portal)
  • open login page in the browser http://localhost:8081/login and login using credentials for the instance

Package manager

All APIHUB Frontend repositories are using NPM as a package manager.

GitHub NPM Registry

We use GitHub NPM Registry for publishing packages.

GitHub NPM registry requires authentication for installing packages from it. So, create a Personal Access Token (classic) with a read:packages scope on a GitHub and specify it in per-user (or global) .npmrc file.

//npm.pkg.github.com/:_authToken="<GITHUB_PAT>"

Publishing Packages

All packages should be published by CI processes which are set up for the repositories.

Do not publish NPM packages manually.

Testing

APIHUB frontend components could have a unit tests, screenshot tests and E2E tests or combination of thereof.

Make sure existing tests are green and new tests of appropriate type are added before submitting PR.

Unit testing

We use Jest for unit testing.

Use NPM script test to run unit tests.

Screenshot testing

Several APIHUB UI components have screenshot (also called snapshot) tests.

These are

Use NPM script screenshot-test:docker to run screenshot tests locally.

Note, that you need to setup WSL with Podman Desktop in order to be able to run screenshot tests locally.

End to end testing

We use Playwright for E2E testing.

See ui-tests for the instructions how to run Playwright tests.

Setup WSL with Podman Desktop

<TBD>, move from https://github.com/Netcracker/qubership-apihub/issues/36

Architecture

Auxiliary components

API Specification Processing Stack

API Specification Rendering Stack

UI

Cross-cutting feature development

NPM link

Specify dependencies

Publishing to NPM registry

Update dependencies

Code Style

Linting

APIHUB VSCode extension

Technical Debt Management

NPM Scripts

Storybook

Code Review Process

GitHub Workflows

UI Development

Shared components

Clone this wiki locally