Skip to main content
Version: Next

UI Development

To develop the UI you need to install Node.js and pnpm. 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 as Single-Page-Application accessing the Woodpecker REST api.


The UI code is placed in web/. Change to that folder in your terminal with cd web/ and install all dependencies by running pnpm install. For production builds the generated UI code is integrated into the Woodpecker server by using go-embed.

Testing UI changes would require us to rebuild the UI after each adjustment to the code by running pnpm 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

Start the UI server locally with hot-reloading by running: pnpm 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 section, you should now be able to access the UI under 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
    • 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 (similar to Tailwind)
    • use Windicss classes where possible
    • if needed extend the Windicss config to use new classes
  • Vite (similar to Webpack)
  • Typescript
    • avoid using any and unknown (the linter will prevent you from doing so anyways 😉)
  • eslint
  • Volar & vue-tsc for type-checking in .vue file
    • use the take-over mode of Volar as described by this guide