@data-fair/app-charts

A simple charting application for DataFair. Also used as an example for the documentation.

It is hosted by npm and the jsdelivr CDN.

An example app can be found here, it uses this dataset.

Context

DataFair is an Open Source Web software developped by Koumoul for publishing data online with complete search and aggregation capabilities, metadata management, mapping functionalities, access control, etc. It can be used as a back office for Open Data platforms, data visualizations, custom search engines and other applications.

DataFair comes with functionalities to facilitate the development, deployment and configuration of small data consuming applications. app-charts is an example of such an application.

Technical stack

This technical stack is just an example of what can be used to build an application for DataFair. It is a quite rich stack for a state of the art development environment. For an application with a more minimalist stack, you can see app-minimal.

• vuejs 3 with the composition API: our favorite framework for client-side code
• vuetify 4: a material design UI framework for vuejs
• vue-i18n: internationalization (session locale, number/percent formats)
• chartjs: simple charting library
• vite: build tool (rolldown) with vite-plugin-vuetify
• playwright: unit and e2e tests

Development Setup

Start by downloading, cloning or forking this repository:

git clone https://github.com/data-fair/app-charts.git
cd app-charts

Install nodejs dependencies for the development environment:

npm install

If you are running a local data-fair instance

Create a dataset in your data-fair instance. You can use this public dataset for example.

Run the development environment (vite + the DataFair dev-server in a zellij layout):

npm run dev

The first run generates a git-ignored .env file holding three free ports (APP_PORT, DEV_SERVER_PORT, E2E_PORT), so several applications can run side by side. An URL banner in zellij shows the dev-server address; configure your application there and edit the configuration, edit the source code, etc.

You can also run only one side of the environment:

npm run dev-app      # vite only (port from .env APP_PORT)
npm run dev-server   # DataFair dev-server only (port from .env DEV_SERVER_PORT)

Else

If you don't have a local data-fair instance, the test suite is fully self-contained (all DataFair APIs are mocked):

npm run test-unit    # unit tests: pure transforms + utils (no server needed)
npm run test-e2e     # e2e tests: full app boot against vite (E2E_PORT from .env)

DataFair application specificity

A DataFair application is mostly like any Web application. You can consume DataFair APIs from any framework for example. But for a seamless integration and multi-configuration management by DataFair you need to respect a few conventions. The following sections are a focus on the files that implement these conventions.

public/config-schema.json

A JSON schema file that describes the expected configuration. DataFair expects this file to be found at the precise path %MY_APP%/config-schema.json. This hand-edited file is the schema (served with its $defs/$ref); TypeScript types are generated from it with npm run build-types (see src/config/schema.ts).

The content of this JSON schema is extended with some annotations used by DataFair to automatically create a configuration form. The details of these annotations can be found in demo of the library we maintain to create these forms: vuetify-jsonschema-form.

index.html

This the root template used to generate the HTML pages of this application. The key element here is this line:

<script>window.APPLICATION=%APPLICATION%;</script>

The string %APPLICATION% will be replaced automatically by the actual content of the configuration, when this application is re-exposed by DataFair. Later code can use the global variable APPLICATION (window.APPLICATION) to start interacting with the DataFair API.
The important parts for DataFair are the df:* meta properties (form version, concept filters, config/state sync, overflow, capture delay) and the application-name / description metas for the catalog.

Deployment

To publish the project, upload it to the global npm registry (you need to be a member of the owner organization).

npm version PATCH|MINOR|MAJOR
npm publish
git push && git push --tags

If the release is a bug fix and you don't want to wait 24h (the cache delay of jsdelivr), you can purge the cache for the index.html file of the minor version in the CDN:

curl https://purge.jsdelivr.net/npm/@data-fair/app-charts@VER/dist/index.html

Replace VER with the minor version number (e.g. 1.0).

To publish a version for testing purposes you can tag it as a pre-release and publish it with the tag "staging".

npm version prerelease --preid=staging
npm publish --tag staging
curl https://purge.jsdelivr.net/npm/@data-fair/app-charts@staging/dist/index.html
git push && git push --tags