Skip to content

Latest commit

 

History

History
132 lines (94 loc) · 6.1 KB

README.md

File metadata and controls

132 lines (94 loc) · 6.1 KB
Raw

CLASS-web

github repo badge Code quality npmjs.com Checked with Biome Research Software Directory Badge Documentation

This is an implementation of the Chemistry Land-surface Atmosphere Soil Slab (CLASS) model that runs entirely in the browser.

For more information on CLASS, see https://classmodel.github.io/.

Web application

The CLASS web application (from apps/class-solid directory) is available at https://classmodel.github.io/class-web.

Command line usage

The class model can be run from the command line, see packages/class/README.md for more information.

Package usage

The class model can be used a package or library, see packages/class/README.md for more information.

Developers

This repository is a so-called monorepo, where multiple packages and application can easily be developed in tandem.

We used TurboRepo for the initial setup, which uses pnpm workspaces under the hood. As such, it is possible to do advanced tricks with Turbo, such as "lint/test/build all apps/packages at once with turbo build", and share tooling configurations across packages/apps, but since this repo is small, we will not rely too much on these features.

Currently the repo is home to the following:

  • packages/
    • class: reimplementation of CLASS in typescript
  • apps/
    • class-solid: web application with a graphical user interface for CLASS

Publish package

To publish a new version of the class package:

  1. Bump version in **/package.json files. They should all have same version.
  2. Commit & push changes to main branch.
  3. Create a new GitHub release
    • Tag version and title should be the same as the version in the package.json file with v prefix.
    • Use Implementation of the Chemistry Land-surface Atmosphere Soil Slab (CLASS) model that runs entirely in the browser. as the description with generated release notes.
  4. A GitHub CI workflow will publish the package to npmjs

Local build

To run a local development version:

git clone [email protected]:classmodel/class-web.git
cd class-web
pnpm install
pnpm dev

Linter & formatter

We use biome to lint and format the code. The following commands are available

# To run linter and formatter use
pnpm format-and-lint
# To fix formatting and some lint errors run
pnpm format-and-lint:fix
# To run other biome comands use
pnpm exec biome --help

To check types, you can run the pnpm typecheck command as other commands ignore types.

Tests

The tests can be run with the following command:

pnpm test

Tech stack

The CLASS package is written in typescript. It uses a JSON schema to define the shape and constraints of a configuration. JSON schema is cross-langanuage and is ideal for sharing the configuration between web-app, library code, and perhaps other implementations of CLASS as well. To validate a configuration it uses the JSON schema together with ajv. Ajv is the reference JSON schema validator in then JS ecosystem.

The CLI uses Commander to parse the command line arguments. Commander is the most popular package for building command line interfaces with sub-command support in Mode.js.

The web application is build with solid.js. Solid is a relatively simple framework for building reactive web applications. With its metaframework SolidStart it is quite easy to pre-render the web application as static pages that can be hosted on github pages. To keep track of form state and errors it uses modular forms package.

We've chosen SolidUI as the basis for the UI. Build after ShadCN, SolidUI provides good-looking, accessible components (powered by Kobalte and tailwind) that can be copy-pasted into the web application and tweaked further as seen fit. It can also do charts, using chart.js, though we might deviate from that later.

To expose the model in a standard way we use the Basic Model Interface (BMI).

To prevent the user interface from getting blocked by running the model we use a Web worker to run the computation in a background task/thread. A Web worker uses messages passing to communicate, this does not fit with the Basic Model Interface so we use comlink to wrap the Web Worker in a BMI class.

To format and lint the code, we use biome as it combines eslint, prettier in one package.

Further plans/ideas

  • Use auto for managing versions/releases
  • Use d3.js for more low-level charting
  • Use AssemblyScript or rust for a faster implementation of CLASS running on web assembly.
  • Use storybook for UI component package