Install the UI Server which bundles the UI.
Copyright (C) 2018-2023 NIWA & British Crown (Met Office) & Contributors.
Cylc is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Cylc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Cylc. If not, see GNU licenses.
# Project setup
yarn install
# start dev server in offline mode (uses mock data, auto-updates the browser page on change)
yarn run serve
# pass options to vite (e.g. to use a different port or expose host)
VITE_OPTIONS='--host myhost' yarn run serve
# build for production
yarn run build
# build for development (rebuilds on change)
yarn run build:watch
# and launch using
cylc gui --ui-build-dir=<cylc-ui-path>/dist/
# Note the incremental rebuild is quite slow so an alternative to build:watch is
cylc gui --no-browser --port=3000 --ServerApp.allow_origin='http://localhost:5173'
# and launch using
yarn run serve:vue --mode development
# start dev server in offline mode, using the build instead of source files
yarn run previewThere are three groups of tests:
- Unit tests
- Component tests
- In-browser tests which mount a single Vue component standalone.
- Framework: Cypress
- Assertions: Chai
- Path:
cypress/component - Command:
yarn run test:component- (For "headless" mode use
yarn cypress run --component --config video=false)
- (For "headless" mode use
- End to end tests
- In-browser tests which load entire pages of the UI using mocked data.
- Framework: Cypress
- Assertions: Chai
- Path:
tests/e2e - Command:
yarn run test:e2e- (For "headless" mode use
yarn run serve cy:run)
- (For "headless" mode use
For coverage:
yarn run coverage:unit
yarn run coverage:e2eThe "offline" mode (aka yarn run serve) which is also used for the end to end
tests is powered by a "mock" data server.
You can find the index of mocked data here:
src/services/mock/json/index.js
Mock data is automatically loaded when the subscription/query issued matches an entry in that file.
See .eslintrc.js for style, to test run:
yarn run lintOr to lint a particular file/directory:
yarn eslint path/to/fileWe are using Vue. The project was originally created with vue-cli, but has switched to Vite with the upgrade from Vue 2 to 3.
The configuration for how the app is served and built is defined in
vite.config.js.
We are currently using the Vuetify component library.
Its configuration is defined in src/plugins/vuetify.js.
We use concurrently for
concurrently running the mock data json-server and the Vite dev server, and
also Cypress. This is configured in scripts/concurrently.js.
There are two aspects of browser compatibility:
- ECMAScript syntax (e.g. does the browser support the optional chaining
operator (
?.)?) - API calls (e.g. does the browser support
Array.prototype.at()?)
The former is handled by Vite. It uses esbuild to transform instances of newer syntax when building.
However, new APIs are not handled and must be polyfilled if deemed necessary.
We define a specification for browser compatibility in
.browserslistrc. See https://github.com/browserslist/browserslist.
- We are not currently using it for the Vite/esbuild configuration because the default is good enough (but we could do in future using a plugin such as esbuild-plugin-browserslist).
- For polyfilling newer APIs, we could use
Babel + core-js which
uses the browserslist specification. Or perhaps the simplest solution is to
use polyfill.io which merely requires adding a
<script>tag toindex.htmlwhich will fetch the listed polyfills only if needed by the user's browser. We could even leave it up to sites to patch their Cylc UI builds with the polyfills they require.
Remember it is not just our source code that must meet our back-compat specification, but our bundled dependencies (e.g. Vuetify) too! Vite/esbuild handles syntax for bundled dependencies.
However the bottom line is that as of 2023, browser support is much less of an issue than it was even a couple of years ago, due to the proliferation of evergreen browsers. The only real concern is bleeding-edge API calls creeping into our source code or runtime dependencies. To catch this, we are using eslint-plugin-compat in CI to scan the build for any such API calls.
Running yarn run build[:watch] outputs the build into the ./dist/ folder.
When running the Cylc Hub, you must remember to point
the static files directory to the location of your ./dist folder.
This way with both Cylc Hub and Cylc UI running, you can work on either -
or both - projects. Changes done in your Tornado application should reflect immediately
or upon process restart. While the changes done in your Vue.js application
will be automatically handled by your build:watch command.
This project utilizes vue-i18n for internationalization. While this project is not part of Vue.js, it is maintained by one of the Vue.js core developers.
Messages for internationalization are kept in JSON files. Look at
src/lang/ for each locale. For example, for British English, the message
files are kept under src/lang/en-GB.
The locale is defined by a variable $i18n, which is accessible in each
component. So in a component you should be able to change the locale -
if necessary - by calling this.$i18n.locale = 'pt-BR'.
After applying changes to the code, might be a good idea to pass the new version of the application through an accessibility tool such as WAVE.
There is also a browser extension which makes testing the development version much easier.
TypeScript is most likely the future for us. It can be adopted gradually. At the moment we only have JSDoc comments which can provide type information in your IDE.