woodpecker/docs/versioned_docs/version-0.15/92-development/03-ui.md
2022-09-01 01:52:52 +02:00

31 lines
2.5 KiB
Markdown

# UI Development
To develop the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api.
## Setup
The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `yarn install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed).
Testing UI changes would require us to rebuild the UI after each adjustment to the code by running `yarn build` and restarting the Woodpecker server. To avoid this you can make use of the dev-proxy integrated into the Woodpecker server. This integrated dev-proxy will forward all none api request to a separate http-server which will only serve the UI files.
![UI Proxy architecture](./ui-proxy.svg)
Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `yarn start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file.
After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000).
## Tools and frameworks
The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing.
- [Vue 3](https://v3.vuejs.org/)
- use `setup` and composition api
- place (re-usable) components in `web/src/components/`
- views should have a route in `web/src/router.ts` and are located in `web/src/views/`
- [Windicss](https://windicss.org/) (similar to Tailwind)
- use Windicss classes where possible
- if needed extend the Windicss config to use new classes
- [Vite](https://vitejs.dev/) (similar to Webpack)
- [Typescript](https://www.typescriptlang.org/)
- avoid using `any` and `unknown` (the linter will prevent you from doing so anyways :wink:)
- [eslint](https://eslint.org/)
- [Volar & vue-tsc](https://github.com/johnsoncodehk/volar/) for type-checking in .vue file
- use the take-over mode of Volar as described by [this guide](https://github.com/johnsoncodehk/volar/discussions/471)