powsybl-network-viewer

Typescript library to integrate network viewers in a javascript project. This library contains three viewers:

• network-area-diagram-viewer, to integrate the SVG representing a graph of voltage levels within a network, the SVG and the corresponding metadata JSON file being generated by powsybl-diagram
• single-line-diagram-viewer, to integrate the SVG representing single-line diagrams, the SVG and the corresponding metadata JSON file being generated by powsybl-diagram
• network-map-viewer, to display the substations / voltage levels on a map

The library is built with the Vite bundler. Node v24+ is required to build with Vite. Use fnm or nvm to select the correct Node version when entering the project directory.

Note:
A .nvmrc file is present in the repository, please run nvm use to use the expected NodeJS version.

The current package manager is set in the "packageManager" field in package.json.
To install it, run:

corepack install

Installation

The library is split into 3 packages to accommodate different use cases:

| Package | Description | | ------------------------------ | -------------------------------------------------- | | @powsybl/network-viewer | Full package with all viewers including NetworkMap | | @powsybl/network-viewer-core | Core viewers (NAD + SLD) | | @powsybl/network-map-layers | Deck.gl layers for map integration |

For full package

npm install @powsybl/network-viewer

This package requires React peer dependencies:

• react, react-dom, react-intl
• @mui/material, @mui/icons-material, @emotion/styled

For Angular/Vue/Vanilla JS applications (React-free)

If you only need the SVG diagram viewers (NetworkAreaDiagramViewer and SingleLineDiagramViewer) without React:

npm install @powsybl/network-viewer-core

Usage:

import {
    NetworkAreaDiagramViewer,
    SingleLineDiagramViewer,
    LayoutParameters,
    SvgParameters,
} from '@powsybl/network-viewer-core';

// Create NAD viewer
const nadViewer = new NetworkAreaDiagramViewer(
    container,
    svgContent,
    metadata,
    minWidth,
    minHeight,
    maxWidth,
    maxHeight,
    parameters
);

// Create SLD viewer
const sldViewer = new SingleLineDiagramViewer(container, svgContent, metadata, options);

For Deck.gl map layers only

npm install @powsybl/network-map-layers

For developers

For development purpose, to install this library locally from an app, you should run these commands in the library project :

• npm install
• npm run build:all
• npm run pack:all

Then in the app project :

• npm install {PATH_TO_LIBRARY}/powsybl-network-map-layers-{LIBRARY_VERSION}.tgz
• npm install {PATH_TO_LIBRARY}/powsybl-network-viewer-core-{LIBRARY_VERSION}.tgz
• npm install {PATH_TO_LIBRARY}/powsybl-network-viewer-{LIBRARY_VERSION}.tgz

Warning : You could encounter ERESOLVE errors from peer dependencies during installation.
Please run npm install --legacy-peer-deps to fix this for developpement context.
Do not merge later changes, it won't happen with version installation from the npmjs repository.
See : https://github.com/npm/cli/issues/8647

Warning : with Create React App, we realised the library was not updating correctly if you try to install the library multiple times. To fix this, run this command from the app after running "npm install"

• rm -Rf node_modules/.cache

For integrators

(Optional) Test your package from library dependent directory

According to PowSyBl branching and release strategy, if you want to publish a new release of powsybl-network-viewer in the NPM package registry, you need to follow the steps below:

1/ Update your main branch to the latest version:

$ cd powsybl-network-viewer
$ git checkout main
$ git pull

2/ Prepare the temporary branch

• Create your temporary branch preparing the release X.Y.0 and bump to your release version.

$ git checkout -b tmp_prepare_release
$ npm --workspaces --include-workspace-root --no-git-tag-version version X.Y.0

• Manually change the version of dependencies in the root package.json to ^X.Y.0
• Update package-lock accordingly and commit the changes.

$ npm i
$ git commit -s -a -S -m "Bump to vX.Y.0"
$ git push -u origin tmp_prepare_release

• Create a pull request from your temporary branch into the main branch.
• Wait until all the CI criteria are fully validated. Then add a commit for your next snapshot version, including the change in the root package.json to ^X.Y+1.0-dev.0.
• You can then push again.

$ npm --workspaces --include-workspace-root --no-git-tag-version version X.Y+1.0-dev.0
$ npm i
$ git commit -s -a -S -m "Bump to vX.Y+1.0-dev.0"
$ git push -u origin tmp_prepare_release

• Tag another maintainer as a reviewer to your pull request so they can approve it.

3/ Merge the pull request

Once it is approved, locally merge it by following these steps:

$ git checkout main
$ git pull
$ git merge --ff tmp_prepare_release
$ git push

After that, create your tag:

$ git tag -s vX.Y.0 <hash of the corresponding commit (bumping to vX.Y.0)>
$ git push origin vX.Y.0

NB: the tag must respect the pattern vX.Y.0.

You can then publish a Release note pointing to your newly created tag.

Please make sure that your release note is comprehensive to all new features and bug fixes of the release and that the migration guide has been updated if necessary.

4/ Publish the new version

• Check out the tag in a fresh repo copy
• Install your packages
• Build the packages – npm will publish the README.md, the package.json files and the dist directory you generated
• Login on the command line to the npm registry
• Publish the package

$ cd $(mktemp -d)
$ git clone https://github.com/powsybl/powsybl-network-viewer.git
$ cd powsybl-network-viewer
$ git checkout vX.Y.0
$ npm install --workspaces --include-workspace-root
$ npm run build:all
$ npm login
$ npm run publish:all

Notes :

• Check license-checker-config.json for license white list and exclusion. If you need to update this list, please inform organization's owners.
• We need to exclude some packages for now :
  • @mapbox/[email protected] is a special license
  • [email protected] is Creative Commons but not correctly described in the package
  • [email protected] is BSD-3-Clause but not correctly described in the package

Contributing

See Contributing.md for explanations on how to contribute to the code.

See Security.md to read about the security policy.