Hex Core: JS

Hex Core JS libraries.

Packages

App Modules

Larger and more app-specific components and functions for use in a React app.

Automata

Finite automata library.

Core

Houses core React functionality to be used in apps and other packages in this repository. Includes basic components, utility functions, general hooks and more.

Charts

Helpful utilities for the recharts package.

Forms

Contains logic and components for managing and displaying forms.

Generator

A code generation CLI tool.

JWT

JSON Web Token (JWT) library.

Log

Logging library.

Permissioning

Library for storing and working with user permissions.

Router

Routing and URL handling library.

SRSL

Parsing tools for Simple Relational Schema Language (SRSL).

Tables

Table library.

Testing

Test utility library.

Uploads

Upload utilities library. Designed to work with uploads.hexinsights.dev.

Usage

Installation

See specific packages for installation instructions, but all should follow the pattern:

npm i @hex-insights/<package>
Copy

And require a local .npmrc file with the following contents:

registry=https://npm.pkg.github.com/hex-insights
Copy

Development

Package Management

This project uses lerna to manage packages.

For more details, see the Development document.

To get inter-dependency to work, do the following. All steps should be done from the root directory.

1. If in a new project, run npm i to install lerna.

   • If not, run npx lerna clean, (hit y and enter), and delete node_modules. Or, manually delete node_modules from each package.

2. Ensure lerna is installed properly by running

   npx lerna --version
   Copy

   If you see the npm installation loading "bar", you will need to double check that lerna was installed locally correctly.

3. You can see which packages lerna knows about by running

   npx lerna list [--graph [--all]]
   Copy

   • list simply lists packages
   • graph will show dependencies
   • all will include dev dependencies

4. Now to install node modules in each package, instead of running npm i in each folder, run

   npx lerna bootstrap --hoist --ignore-scripts
   Copy

   • The bootstrap command will install scripts in each package.
   • The --ignore-scripts flag ensures scripts in any package.json will not be run.
   • The --hoist flag puts any common dependencies between projects in the root node_modules folder. This helps prevent dependency resolution problems.

5. Now we want to build our packages so that inter-dependent packages get the latest versions

   npx lerna run build
   Copy

   the run command simply calls npm run in each package, so here we are just calling npm run build in each package.

6. Finally, run

   npx lerna link
   Copy

   This will "link" inter-dependent packages.

Adding a Package

Packages are creating using create-react-library. After creating a new package using create-react-library, some further configuration is necessary. Use the following command to add a new app (from the packages/ directory):

npx create-react-library <package> --template typescript
Copy

The package.json file must be updated to reflect the correct package name and repository and the .prettierrc should be adjusted to match that of the other packages.

Install the following dev dependencies in the new package:

• typedoc
• http-server (for serving documentation)
• @testing-library/react-hooks and react-test-renderer@^16.9.0 (if package includes exported hooks)

Define the package.json command doc as npx typedoc && npx http-server docs -p 3001, then documentation can be updated and served with npm run-script doc.

Formatting

Format files using prettier—configure to run on save in your editor or run manually with npx prettier --write ..

To run automatically on save with VS Code, add the following to settings.json:

"[typescript]": {
    "editor.formatOnSave": true
},
"[typescriptreact]": {
    "editor.formatOnSave": true
},
"[css]": {
    "editor.formatOnSave": true
}
Copy

Testing

Test coverage is especially important in this repository as these packages will be imported into all/most Hex Insights projects. Run tests in vitest. Test hooks using react-hooks-testing-library.

Documentation

To help teams working on projects using the Hex Core React libraries make sure components and functions are well documented.

Document components using storybook. Stories written for storybook can be used as test cases in tests which simplifies the testing/documentation process. Use the following command to setup storybook in a package:

npx -p @storybook/cli sb init --story-format=csf-ts
Copy

Document components and functions using typedoc. While storybook offers a great way to explore and test components, the documentation capabilities seem to be limited, so standard documentation should be included for components.

Note that component props need to be documented twice: inline docs above each property of the props type (for storybook); and above the component (for typedoc). Possibly this will be fixed in the future with an update to typedoc, which currently supports inline documentation for interfaces but not types, so that documentation can exist only in the type definition.

Before Committing

Before committing changes make sure to run tests and format all files.

Deployment

Packages are registered on the GitHub Package Registry and deployed automatically using GitHub Actions. To update a published package, increment the package version number in the relevant package.json file and the package will be updated when the changes are merged into the main branch.