Build

Overview

GitLab Knowledge Graph has two parts: a backend (Rust workspace crates) and a frontend (Node workspace packages).

Backend (Rust crates): define the data model, API, and services (e.g., crates/http-server-desktop, crates/database, crates/indexer).
Frontend (Node workspace packages):
- @gitlab-org/gkg (packages/gkg/src): TypeScript bindings generated from Rust via ts-rs.
- @gitlab-org/gkg-frontend (packages/frontend): Vue + Vite UI that depends on @gitlab-org/gkg.

The http-server-desktop crate embeds the frontend dist into the final gkg binary. Docs (packages/docs) build separately.

Build order

Generate TypeScript bindings from Rust via ts-rs.

mise run bindings-gen
# equivalent
cargo test export_bindings --features no-frontend

We commit generated bindings to git; rebuild them whenever you change the Rust types that drive the API (primarily in crates/http-server-desktop).

Build the frontend packages.

npm ci
npm run build --workspace=@gitlab-org/gkg-frontend

The Rust HTTP server (crates/http-server-desktop) embeds packages/frontend/dist into the binary. Without --features no-frontend, the binary requires these assets to exist.

Build the main binary (gkg).

cargo build --release --bin gkg

ⓘ If you do not need the web UI, you can skip Node installation and frontend builds. Use the no-frontend feature when building:

cargo build --release --bin gkg --features no-frontend

Docs build:

npm ci
npm run build --workspace=docs

ⓘ Please check the mise.toml configuration file for many useful commands.

Speed up your builds

Builds with the --release profile can take significantly more time than debug builds. Unless you want to run benchmarks, prefer debug builds to test the functionality of gkg.

Kuzu dynamic linking

By default, Kuzu is built and statically linked to gkg, which makes the build at least much slower. For quicker builds and tests, we recommend downloading the Kuzu binaries and using dynamic linking instead. To do this:

Download and unpack the distributed libkuzu library files.
Set up your environment variables:

export KUZU_SHARED=1
export KUZU_INCLUDE_DIR=/path/to/kuzu/include
export KUZU_LIBRARY_DIR=/path/to/kuzu/lib

Now cargo build will skip the complex Kuzu build step!

⚠️ Make sure your dynamic libraries match the Kuzu version specified in Cargo.toml, otherwise you may encounter errors during build or runtime!

Code Quality Requirements

The project enforces strict code quality standards:

Unused imports fail builds: The workspace is configured with unused_imports = "deny", meaning any unused imports will cause compilation to fail
Clippy linting: All clippy warnings are treated as errors (-D warnings)
Formatting: Code must pass rustfmt checks

Run quality checks locally:

# Check for unused imports and other issues
cargo check --workspace

# Run clippy linting (matches CI configuration)
mise run rust-clippy

# Format code
mise run rust-fmt:fix

The pre-commit hooks will automatically fix most issues, but it’s good practice to run these commands manually during development.