Develop

Develop 🧑‍💻

Developing for Renku UI is easy! You will only need a recent version of NodeJS, NPM and Git. You might need a few other tools, depending on which approach you choose.

This page refers to the React-based client and the Cypress tests. There is also an Express-based server, but it's deprecated and will be removed.

Getting started 🚀

Once you clone the Renku UI repository locally, go into the client folder and install the dependencies with the npm install command. You can now start the Vite server with the command npm run start and the interface will be available at the local URL localhost:3000.

The web interface requires interacting with backend components, and there are two ways to get the API responses you need:

• Create a full Renkulab deployment for development: this approach is recommended for most scenarios but requires access to the SDSC Kubernetes infrastructure.
• Mock the responses from the APIs: this is quick and has no requirements, well suited for quick changes but tedious if you need to mock many new responses.

Full deployment 🏙️

Having a full Renkulab dev deployment is the best way to develop since you have all the infrastructure and can fully use the UI. It is easy and quick to get if you have access to the SDSC Kubernetes infrastructure, available to all the official Renku team members and extendable to other SDSC employees and collaborators.

You can leverage our CI automation on GitHub: create a new PR with at least one commit and include a line with the text /deploy in the description. This will trigger the acceptance-tests workflow that deploys a dev instance of Renkulab reachable at the URL https://renku-ci-ui-<PR_number>.dev.renku.ch/. The process takes a few minutes and Renku Bot will post the exact URL. The deployment can be further customized (renku-action reference).

You need to install locally Telepresence to swap the renku-ui pod with a local instance of the UI; that requires installing Docker and Kubectl too.
Run the run-telepresence script, provide the PR number, and access the instance from the URL you got from Renku Bot. Mind that it takes up to a minute for the new Telepresence-injected pod to start serving pages; until that moment, the page you get won't come from your local code.

When you stop Telepresence, you'll see a 50x page for a short while and then the Kubernetes infrastructure will spin up a new pod serving the UI from the latest commit in the PR.
Mind that Telepresence might get stuck when the connection with your laptop is suddenly lost. If the 50x page persists, you can try to execute telepresence uninstall --all-agents. Wait until a new pristine pod comes online (i.e. the UI loads again) if you need to re-start Telepresence.

Alas, at the moment we don't support out-of-the-box using a public instance like renkulab.io. Deploying all the infrastructure locally or in another Kubernetes cluster is technically feasible but overkill.

Mock responses 🎭

You can use the Cypress tests in the tests folder to mock API responses easily. There are no additional requirements.

See the Tests section for further information.

Coding guidelines 📜

If you wish to contribute new Pull requests, your code must satisfy specific standards we have set to simplify collaboration with the broader community.

• Stick to our tech stack and use the right tool for the right purpose. This way, we keep our codebase consistent. You can learn about the framework we use in the Architecture page.

• Run the linter. This points out some bad coding practices, saving time to reviewers and trying to keep out common bugs. We use ESLint with a few standard plugins and some customizations. You can see the status of your code by running npm run lint or integrating it in your IDE of choice.

• Adhere to our Coding Guidelines. This fills a few gaps that our linting tools cannot easily catch and helps keep the codebase consistent to make life easier for developers and reviewers. We have no automation to help with this; reviews will point out inconsistencies.

• Try to use similar UX patterns. This makes pages consistent and keeps the UI intuitive for the users. When in doubt, check similar components on other pages, access the Storybook section available at <base_URL>/storybook/ with a list of common patterns and examples, or ask to a maintainer to get guidance on the best approach.

• Format your code. We use Prettier to keep the style as consistent as possible. This helps developers and reviewers, partially avoiding the use too many different flavors of TypeScript. You can run npm run format to format all the files automatically, or use the Husky automation we have in the main folder (install with npm install) to automatically format your code when committing. Prettier also integrates very well with the most common IDEs.

• Update local tests. We have unit tests and Cypress tests. They ensure complex functions work fine and React components show as expected. Depending on the changes, you might need to add new tests and/or update existing ones. Refer to the Architecture page for further information.