Project specific guidelines

Here is an overview of specific guidelines for each project.

Designer

The files located in src/Designer belong to the Studio tool. This is developed with frontend code written in Typescript and backend code written in C#.

Frontend

The files located in src/Designer/frontend belong to the frontend part of the Studio tool.

Technologies

The Designer frontend is a React-based app written in Typescript and built with Vite. Additionally, key tools include Tanstack Query, React Router, CSS modules, and I18Next.

Tools for testing and quality assurance

We use Jest for unit tests of the Typescript code, combined with React Testing Library for testing React functionality.

Using test ID's and the testids file

Both Playwright and React Testing library supports locating DOM elements with the data-testid attribute. Using this should be a last resort, but when it's needed, the test ID should be placed in a variable in the testids.js file. This allows us to share test ids between the frontend code and the test files in both component and end-to-end tests, and it makes it easy to see where they are used. This file should not be used for anything else than data-testid variables.

File structure

Folder	Description
admin
app-development	React app for the app editing tool.
app-preview	React app for previewing apps.
dashboard	React app for the dashboard.
language	Texts.
libs	Internal libraries used across the apps.
packages	Internal libraries, but more extensive than those in libs. Except for shared, each of these is only used in one place. We should aim to move these closer to where they are used or to libs.
resourceadm	Resource admin app. Managed by the authorisation team.
scripts	Various helper scripts for developers.
studio-root	React app for the main page.
testing	Contains end-to-end tests, usability pattern tests, and various test tools used across the apps.

The libs folder

The libs folder is the innermost layer of the frontend architecture, containing building blocks that we use all across the frontend code. It should not have any dependencies to other things in the frontend folder. Also, the number of external dependencies in each library should be strictly limited.

Here is a graph that shows how the different libraries are tied to each other internally. An arrow means that the thing it points from depends on the thing it points to. To avoid circular dependencies, arrows should only point from left to right in this graph.

graph LR
    subgraph Independent of React
        pure-functions --> guard
        browser-storage --> pure-functions
        browser-storage --> guard
    end
    subgraph React-dependent stuff
        hooks --> pure-functions
        hooks --> guard
        components --> pure-functions
        components --> guard
        components --> icons
        components --> hooks
        feature-flags --> pure-functions
        feature-flags --> guard
        feature-flags --> hooks
        content-library --> components
        content-library --> icons
        content-library --> hooks
        content-library --> pure-functions
        content-library --> guard
        feedback-form --> components
        feedback-form --> icons
        feedback-form --> hooks
        feedback-form --> pure-functions
        feedback-form --> guard
        assistant --> components
        assistant --> icons
        assistant --> hooks
        assistant --> pure-functions
        assistant --> guard
    end

Loading

Backend

More information to come.

Local development

More information to come.

End-to-end tests

We have set up end-to-end tests using Playwright. These are located in src/Designer/frontend/testing/playwright.

App

The files located in src/App are libraries used by the apps set up by the Studio tool.

app-frontend-react

More information to come.

app-lib-dotnet

More information to come.