Skip to content
On this page


In First App > UI Design we explored different ways to design our app and found out that there are two options: UI files & creating widgets manually in code.

However, there's now a markup language that compiles to UI files / GtkBuilder XML called Blueprint.


Reading Blueprint's docs is highly recommended as this page won't cover everything.


blueprint-compiler will most likely not be available by default on your machine.

Check if it's available on your OS' repos and install it. If it's not, you have to install it manually:

$ git clone
$ cd blueprint-compiler
$ meson . _build
$ ninja -C _build install

blueprint-compiler should now be available on PATH!

Getting Started

Blueprint files are going to first be compiled into GtkBuilder XML before we bundle them into the GResource.

  • We don't want to commit them, so we are going to add the following to our .gitignore file:
  • We will place our .blp (Blueprint) files in ./data/ui/ just like our UI files, but we will reference to their compiled versions (under ./data/ui/compiled/) in our data/APP_ID.gresource.xml. For example, if we want to bundle ./data/ui/about.blp, we are going to add the following:
<?xml version="1.0" encoding="UTF-8"?>
  <gresource prefix="/path/for/bundle">
    <file compressed="true" preprocess="xml-stripblanks">ui/compiled/about.ui</file>
  • We want to compile them every time we compile the app, so we are going to use macros to call blueprint-compiler. Add the following in your src/modules/ (or wherever you compile your GResource bundle):
    `blueprint-compiler batch-compile ./data/ui/compiled ./data/ui/ ./data/ui/*.blp`


Compiling of Blueprint files has to be done before you compile your GResource, so place it above Gio#register_resource.


Wrapping it in {% %} is required.

Gio.register_resource("data/APP_ID.gresource.xml", "data")
  • And lastly, refer to them as usual:


Notice that it's under the /compiled/ folder in the GResource too.

Porting UI files to Blueprint

blueprint-compiler offers a port command that automatically ports UI files / GtkBuilder XML to Blueprint:

  • First of all, change the current directory to the folder your UI files are, e.g. ./data/ui/, otherwise it will recursively search for UI files including in folders like lib/ and mess with the shards:
$ cd ./data/ui/
  • Then run blueprint-compiler port and respond with the following:
$ blueprint-compiler port

STEP 1: Create subprojects/blueprint-compiler.wrap
Create subprojects/blueprint-compiler.wrap? [y/n] n

STEP 2: Set up .gitignore
Create .gitignore with '/subprojects/blueprint-compiler'? [y/n] n

STEP 3: Convert UI files
will port ./app.ui -> ./app.blp

All files were converted.
Save these changes? [y/n] y

STEP 4: Set up
NOTE: Depending on your build system setup, you may need to make some adjustments to this step.

STEP 5: Update
po/ does not exist, skipping

STEP 6: Clean up
Delete old XML files? [y/n] y
STEP 6: Done! Make sure your app still builds and runs correctly.


We don't use meson in Crystal, making many of the above tasks useless.


Blueprint doesn't support everything UI files do, porting might error. If that happens, try removing the section it complains about.


Blueprint files use the gettext syntax to mark strings for translation (see Blueprint Docs#translations), e.g.:

Label {
    label: _("Welcome to my app!");
  • And then run xgettext to generate the strings. Blueprint files require some extra flags that are not mentioned in the other pages:
$ xgettext --files-from=po/POTFILES --output=po/APP_ID.pot --from-code=UTF-8 --add-comments --keyword=_ --keyword=C_:1c,2


Without the extra flags, strings won't be extracted from the .blp files.


We need to install blueprint-compiler in the sandbox:


    "modules": {
            "name": "blueprint-compiler",
            "buildsystem": "meson",
            "sources": [
                "type": "git",
                "url": "",
                "branch": "main"


  - name: blueprint-compiler
    buildsystem: meson
      - type: git
        branch: main

UI Design

Currently, there are two apps that are able to handle Blueprint: Workbench and GNOME Builder.

Screenshot of the app Workbench showing on the left side a Blueprint file and on the right side its preview


Tiny Stats got updated with a Blueprint action (with translations, GResource and everything else) on this commit.

Released under a Creative Commons Zero v1.0 Universal License