50 lines
3.2 KiB
Markdown
50 lines
3.2 KiB
Markdown
# Contributing to the openHAB UI
|
|
|
|
The [standard contributing and community guidelines for the openHAB project](https://github.com/openhab/openhab-core/blob/main/CONTRIBUTING.md), including signing off your commits, also apply for the development of the UI.
|
|
|
|
The repository for web user interfaces, including this project, is located at https://github.com/openhab/openhab-webui and the code of this project, including this file, is found in the `bundles/org.openhab.ui` folder.
|
|
|
|
## Prerequisites
|
|
|
|
This project is built using [Vue.js](https://vuejs.org/), [webpack](https://webpack.js.org/) and [Framework7](https://framework7.io).
|
|
|
|
You need Node 16.14.0 or later and npm 8.6.0. Change to the `web` directory, gather the necessary dependencies with `npm install` then the scripts below will be available.
|
|
|
|
## NPM Scripts
|
|
|
|
* `npm start` - run the development server (see below)
|
|
* `npm run build-prod` - build web app for production (note: no need to prepare a production version when submitting a PR, the build server will do it)
|
|
* `npm run build-cordova-prod` - build cordova's `www` folder from source and build a Cordova app
|
|
* `npm run test:unit` - start the Jest test runner and run the unit tests
|
|
* `npm run test:unit:watch` - start the Jest test runner, run the unit tests, keep running and watch for changes
|
|
* `npm run test:e2e` - start Cypress and run the e2e tests
|
|
* `npm run test:e2e:gui` - open the Cypress GUI
|
|
|
|
## Development server
|
|
|
|
Before starting the development server with `npm start`, you should have an instance of openHAB (either a complete distribution or the demo app) running on _localhost:8080_.
|
|
The development server will run on the next available port (for instance, 8081) and proxy requests to well-known openHAB URLs like the REST API or icon servlet, forwarding them to their equivalent on port 8080.
|
|
If you wish to change the target of these forwards and use a remote instance, set the `OH_APIBASE` environment variable to the desired URL (e.g. `OH_APIBASE=http://openhab-dev:8080`) before running `npm start`.
|
|
|
|
You can also run the unit tests (`test/jest`) and e2e (`test/cypress`) tests using the abovementioned commands.
|
|
Cypress is configured to assume the development server is running on port 8081 - you can change that in `cypress.json` but remember not to commit.
|
|
You can also use Majestic GUI to run the unit tests and temporarily collect code coverage and view coverage reports (it is disabled by default for performance reasons): install it globally with `npm install -g majestic`, and run `majestic` in the root web folder to open Majestic in a browser window.
|
|
|
|
## PWA
|
|
|
|
This is a PWA. Don't forget to check what is inside of your `service-worker.js`. It is also recommended that you disable the service worker (or enable "Update on reload") in your browser's dev tools during development.
|
|
|
|
## Cordova
|
|
|
|
The Cordova project is located in the `cordova` folder. You shouldn't modify content of the `cordova/www` folder. Its content will be correctly generated when you call `npm run cordova-build-prod`.
|
|
|
|
## Documentation & Resources
|
|
|
|
### Framework7
|
|
|
|
* [Framework7 Core Documentation](https://framework7.io/docs/)
|
|
* [Framework7 Vue Documentation](https://framework7.io/vue/)
|
|
|
|
* [Framework7 Icons Reference](https://framework7.io/icons/)
|
|
* [Community Forum](https://forum.framework7.io)
|