❯ direnv allow
direnv: loading ~/Development/lol/clan/git/clan/clan-core/pkgs/ui/.envrc
direnv: loading ~/Development/lol/clan/git/clan/clan-core/.envrc
direnv: using flake
direnv: nix-direnv: Renewed cache
switch to another dev-shell using: select-shell
direnv: using flake .#ui --builders
path '/home/brian/Development/lol/clan/git/clan/clan-core/pkgs/ui' does not contain a 'flake.nix', searching up
direnv: ([/nix/store/rjnigckx9rmga58562hxw9kr5hynavcd-direnv-2.36.0/bin/direnv export zsh]) is taking a while to execute. Use CTRL-C to give up.
path '/home/brian/Development/lol/clan/git/clan/clan-core/pkgs/ui' does not contain a 'flake.nix', searching up
direnv: nix-direnv: Renewed cache
switch to another dev-shell using: select-shell
/home/brian/.config/direnv/lib/hm-nix-direnv.sh:3858: /home/brian/Development/lol/clan/git/clan/clan-core/pkgs/ui/clan-app/.local.env: No such file or directory
direnv: export +AR +AS +CC +CLAN_CORE_PATH +CONFIG_SHELL +CXX +DETERMINISTIC_BUILD +GETTEXTDATADIRS +GETTEXTDATADIRS_FOR_BUILD +GETTEXTDATADIRS_FOR_TARGET +GIT_ROOT +GSETTINGS_SCHEMAS_PATH +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +PC_CONFIG_FILES +PKG_ROOT_CLAN_APP +PKG_ROOT_UI +PKG_ROOT_WEBVIEW_UI +PRJ_ROOT +PYTHONHASHSEED +PYTHONNOUSERSITE +PYTHONPATH +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +WEBVIEW_LIB_DIR +_PYTHON_HOST_PLATFORM +_PYTHON_SYSCONFIGDATA_NAME +__structuredAttrs +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +dontAddDisableDepTrack +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +preferLocalBuild +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~GDK_PIXBUF_MODULE_FILE ~GI_TYPELIB_PATH ~PATH ~XDG_DATA_DIRS

Once that has loaded, you can run the local dev environment by running:

$ process-compose --use-uds --keep-project -n app

This will start a process-compose instance containing two processes:

clan-app-ui which is a background process running a vite server for ./ui in a hot-reload fashion
clan-app which is a foreground process, that is started on demand and provides the webview wrapper for the UI.

Wait for the clan-app-ui process to enter the Running state, then navigate to the clan-app process and press F7. This will start the webview window and bring clan-app's terminal into the foreground, allowing for interaction with the debugger if required.

If you need to restart, simply enter ctrl+c and you will be dropped back into the process-compose terminal. From there you can start clan-app again with F7.

Note

If you are interacting with a breakpoint, do not continue/exit with ctrl+c as this will introduce a quirk the next time you start clan-app where you will be unable to see the input you are typing in a debugging session.

Instead, exit the debugger with q+Enter.

Follow the instructions below to set up your development environment and start the application:

Storybook

We use Storybook to develop UI components. It can be started by running the following:

$ process-compose --use-uds --keep-project -n storybook

This will start a process-compose instance containing two processes:

storybook which is the main storybook process.
luakit which is a webkit-based browser for viewing the stories with. This is the same underlying engine used when rendering the app.

You can run storybook tests with npm run test-storybook. If you change how a component(s) renders, you will need to update the snapshots with npm run test-storybook-update-snapshots.

Start clan-app without process-compose

Navigate to the Webview UI Directory

Go to the clan-core/pkgs/clan-app/ui directory and start the web server by executing:
```
npm install
vite
```
Start the Clan App

In the clan-core/pkgs/clan-app directory, execute the following command:
```
./bin/clan-app --debug --content-uri http://localhost:3000
```

This will start the application in debug mode and link it to the web server running at http://localhost:3000.

Debugging Style and Layout

# Enable the GTK debugger
gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true

# Start the application with the debugger attached
GTK_DEBUG=interactive ./bin/clan-app --debug

Appending --debug flag enables debug logging printed into the console.

Profiling

To activate profiling you can run

CLAN_CLI_PERF=1 ./bin/clan-app

Library Components

Note:

we recognized bugs when starting some cli-commands through the integrated vs-code terminal. If encountering issues make sure to run commands in a regular os-shell.

lib-Adw has a demo application showing all widgets. You can run it by executing

adwaita-1-demo

GTK4 has a demo application showing all widgets. You can run it by executing

gtk4-widget-factory

To find available icons execute

gtk4-icon-browser

Error handling

Error dialogs should be avoided where possible, since they are disruptive.

For simple non-critical errors, toasts can be a good alternative.

README.md Unescape Escape

Clan App

Getting Started