OpenSight User Interface Component Library

About

This TypeScript project contains all React components for the new corporate design. This project uses SWC for production builds and SWC for test compilation.

For documentation, Storybook is used. A published version can be found on https://storybook.greenbone.io.

Prerequisites

Install npm dependencies npm install

Build

To create a production build use npm run build:source and npm run build:types.

• npm run build:source transpiles and bundles the ./src files into ./lib
  • For this SWC is used
  • Configuration for SWC is located at
    • ./swcrc/./swcrc.production for transpilation and minification
    • ./spack.config.js for bundling
• npm run build:types generated Type definition from ./src into ./types
  • For this TSC is used.
    • ./tsconfig[.XXX].json is used

Why SWC?

SWC is 20x faster than Babel on a single thread and 70x faster on four cores.

Test

To tun all tests run npm run test.

To simulate the pipeline process npm run pipeline

Storybook

Storybook is in the opensight-storybook directory. Please read about the instructions in the opensight-storybook readme

Development

Development inside component library

For isolated component development inside the library you can start storybook and a local file-watcher using:

1. Start storybook: lerna run storybook
2. Build opensight-ui-components on file changes: npm run build:watch

Note: This only adjusts the raw javascript files and NOT the types.

To have working types you need to build the types with npm run build:types

For building the source files and types together on each file change, you can run this command: lerna watch -- lerna run build --scope=@greenbone/opensight-ui-components.

Important: Sometimes storybook crashes on rebuilding the os-ui-components repo. Restarting storybook helps.

Use the local development version in other projects

Common situation: Edit library component which is used in another frontend.

Hot reload

This will not reload the changed TypeScript types. It will just rebuild and bundle the files. The FE will instantly replace the components inside the browser using HMR.

UI lib

Start a file watcher, that automatically rebuilds once a file changes npm run build:watch. This simply rebuilds the ./lib folder.

CAUTION: This does NOT rebuild the types. Intellisense and other autocompletion features of your IDE won't work correctly for the changed components.

FE

The given snippet works with vite. If you use another building/development framework, please visit the documentation and see if aliases can be set. This shouldn't be a problem for rollup based bundlers.

Add this snipped to the vite.config.ts in the root of the FE project. Adjust the relative path if needed

const alias = (mode: string) =>
    mode === "local-ui" ? { "@greenbone/opensight-ui-components": `${process.cwd()}/../opensight-frontend-components/packages/opensight-ui-components` } : {}

This basically tells vite/rollup to exchange the import path "@greenbone/opensight-frontend-components" with the local path to the UI lib repo

Adjust the export to be a function (If you currently just exported the config object)

export default ({ mode }) => { <<<< This
    process.env = {
        ...process.env,
        ...loadEnv(mode, process.cwd()),
    }
    .
    .
    .

Add the alias property to the actual config export (resolve.alias)

        resolve: {
            preserveSymlinks: true,
        >>> alias: alias(mode),
            dedupe: [
                "react-i18next",
                "@mantine/*",
                "@mantine/core",
                "react",
                "react-dom",
            ],
        },

Add an npm script shortcut to start with the local-ui mode

    "dev": "vite",
    "dev:ui": "vite --mode local-ui", <<<< This
    "build": "tsc -p tsconfig.prod.json && vite build",

Now you can run npm run dev:ui to start the frontend with the local version of your UI lib. Keep in mind that before using this, you should run the build watcher or a simple build in the UI library.

Correct types

Providing locally adjusted types is more tricky as TypeScript cannot leave the root of the project. To achieve instant type safety and autocompletion, we have to link the local UI library into the FE dependencies using npm link ../opensight-frontend-components/packages/opensight-ui-components. Adjust the path if necessary.

NOTE: This will change the dependencies in your FE project. Reset all links before you push your changes. To reset all links run npm install. Also, having locally linked dependencies might crash unit tests.

You can validate a successful linking by either checking the node_modules manually or check if you see the changes in the FE

HMR and Types

finally you can use the HMR and Typing technique together by:

• [FE] Linking the local UI lib npm link ../opensight-frontend-components/packages/opensight-ui-components
• [UI lib terminal 1] npm run build:watch
• [UI lib terminal 2] npm run build:types keep in mind to run this everytime you change the types
• [FE] npm run dev:ui

UI lib

After you adjusted the types, make sure to run npm run build:types to rebuild the types.

Unit testing components inside the locally installed UI library:

Creating a tarball of the UI lib and installing it (Does not feature instant reload, needs to be done after each change)

You could do this manually with npm pack and npm install. Or you can use the npm package install-local.

Using install-local:

1. run npx install-local --save <path-to-library>

Troubleshooting

No visible changes

Vite caches the dependencies. To flush the cache, either delete the node_modules/.vite folder or start the service with the --force flag e.g npm run dev -- --force. The -- is a must to pass the args to the script shortcut (in this case vite)

Type duplications

If you run into typescript errors. Try to remove the node_modules/@types module from the UI libs node_modules.

This might happen because the modules imported from node_modules/@greenbone/opensight-ui-components use the types from node_modules/@greenbone/opensight-ui-components/node_modules/@types. This can cause duplication errors when using different type versions

Credits

| Dependency | License | Source-code location | |----------------|-----------|----------------------| | caniuse-lite | CC-BY-4.0 | caniuse.com |

Maintainer

This project is maintained by Greenbone AG.

Contributing

Your contributions are highly appreciated. Please create a pull request on GitHub. Bigger changes need to be discussed with the development team via the issues section at GitHub first.

License

Copyright (C) 2022-2024 Greenbone AG

Licensed under the GNU Affero General Public License v3.0 or later.