@ecmwf.int/app-template

v2.0.0

Published

3 months ago

ECMWF application template

Downloads

474

0High
0Medium
0Low

ecmwf

ECMWF app template

Installation

npm

$ npm install "@ecmwf.int/app-template"

yarn

$ yarn add @ecmwf.int/app-template

Usage

To run it manually:

npm

 $ npx ecmwf-app-template -c ./path/to/config/file

yarn

 $ yarn ecmwf-app-template -c ./path/to/config/file

It might be a good idea to automate the process of generating the template. It could be done in various ways depending on particular requirements.

Example configuration of package.json to include generating template using npm 'pre' hooks.

{
  "scripts": {
    "generate-template": "yarn ecmwf-app-template -c template.config.json",
    
    "prestart": "yarn generate-template",
    "start": "command-to-start-app-server",
    
    "prebuild": "yarn generate-template",
    "build": "command-to-app"
  }
}

Configuration

Available configuration options:

| Option | Required | Default | Description | |-----------------|----------|---------|--------------| | output | Yes | — | Output directory path | | title | Yes | — | Document title | | appName | Yes | — | Application Name | | layout | Yes | — | Type of layout ('contained' or 'fluid') | | authHost | Yes | — | Authentication endpoint host | | authRedirect | No | false | Append the current page URL to the login link as a query param so the IAM provider (e.g. Keycloak) returns the user here after login | | authRedirectParam | No | next | Name of the redirect query param added when authRedirect is enabled; must be non-empty and contain only letters, digits, _, . or - | | userConfigPath | No | /frontend/config | Path appended to authHost when fetching the user/auth config endpoint; must start with / | | gtmId | No | — | Google Tag Manager ID | | headBlock | No | — | Block of content injected into the head of the page| | contentBlock | No | — | Block of content injected into the main content of the page| | helpBlock | No | — | Block of content injected into the help dropdown| | userMenuBlock | No | — | Block of content injected into the logged-in user dropdown| | settingsBlock | No | — | Block of content injected into the settings dropdown, below the color scheme switch | | colorScheme | No | false | Show the light/dark/auto switch and drive the page color scheme | | defaultColorScheme | No | auto | Initial scheme before the user picks one: auto, light or dark |

Color scheme (dark mode)

Set "colorScheme": true to render a light/dark/auto switch in the header. The template owns the decision and publishes the resolved scheme so the embedded app can react:

<html data-theme="light|dark"> — always a concrete value (auto is resolved from prefers-color-scheme at load and re-resolved live while it stays on auto). This is the primary hook for CSS.
color-scheme is set on <html> so native UI (scrollbars, form controls) matches.
A ecmwf-template:colorschemechange event fires on window with detail: { resolved, preference } for JavaScript consumers (charts, maps, canvas).

The user's choice persists in localStorage under ecmwf-template:color-scheme. An inline head script applies the scheme before first paint, so there is no flash on load.

The ECMWF header/footer keep their fixed branding; only the embedded app responds to the switch.

The settings dropdown appears when colorScheme is enabled and/or a settingsBlock is provided. Use settingsBlock to add your own settings entries (e.g. links) below the switch — the same file-inlining mechanism as helpBlock/userMenuBlock.

Material UI (v9+) integration

The app must key its theme off the same attribute the template sets, and must not run MUI's own color-scheme manager (InitColorSchemeScript / useColorScheme) — the template owns the attribute:

import { createTheme, ThemeProvider, CssBaseline } from '@mui/material';

const theme = createTheme({
  colorSchemes: { light: true, dark: true },
  cssVariables: { colorSchemeSelector: '[data-theme="%s"]' },
});

// <ThemeProvider theme={theme}><CssBaseline />…</ThemeProvider>

MUI then emits [data-theme="light"] / [data-theme="dark"] variable blocks that react to the template flipping the attribute, with no runtime coordination.

Environment variables

Configuration file supports environment variables by using %VARIABLE_NAME% syntax.

Configuration file example

{
  "title": "ECMWF | Title",
  "appName": "Application Name",
  "output": "./public",
  "layout": "fluid",
  "headBlock": "./template/head.html",
  "contentBlock": "./template/content.html",
  "helpBlock": "./template/help.html",
  "userMenu": "./template/userMenu.html",
  "authHost": "%ECMWF_APP_TEMPLATE_AUTH_HOST%"
}

Development

There are two aspects of the package.

Template development

Building a template:

$ yarn build-template

Starting a development server:

$ yarn start

CLI tool and a binary to generate the template

Building a cli tool:

$ yarn build-cli

Publishing

npm

Bump a version:

$ npm version major|minor|patch

Publish:

$ npm publish

yarn

$ yarn publish

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ECMWF app template

Installation

npm

yarn

Usage

npm

yarn

Configuration

Color scheme (dark mode)

Material UI (v9+) integration

Environment variables

Configuration file example

Development

Template development

CLI tool and a binary to generate the template

Publishing

npm

yarn