Instead of duplicating ~600 lines of build configuration across every module, this library lets you define a module with a single metadata.json file and your source code.

Without Builder	With Builder	Reduction
~600 lines config	~70 lines config	88%
5 config files	2 config files	60%

Quick Start

1. Create your module directory

my-module/
├── metadata.json        # Single config file (~30 lines)
├── flake.nix            # Minimal flake (~10 lines)
├── CMakeLists.txt       # CMake config (~25 lines)
└── src/                 # Source files
    ├── my_module_interface.h
    ├── my_module_plugin.h
    └── my_module_plugin.cpp

2. Define your module in `metadata.json`

{
  "name": "my_module",
  "version": "1.0.0",
  "type": "core",
  "category": "general",
  "description": "My custom Logos module",
  "main": "my_module_plugin",
  "dependencies": ["waku_module"],

  "nix": {
    "packages": {
      "build": ["protobuf"],
      "runtime": ["zstd"]
    },
    "external_libraries": [],
    "cmake": { "find_packages": [], "extra_sources": [] }
  }
}

3. Create a minimal `flake.nix`

{
  inputs = {
    logos-module-builder.url = "github:logos-co/logos-module-builder";

  };

  outputs = inputs@{ logos-module-builder, ... }:
    logos-module-builder.lib.mkLogosModule {
      src = ./.;
      configFile = ./metadata.json;
      flakeInputs = inputs;
    };
}

4. Build your module

git init && git add -A   # Nix needs files tracked by git
nix build                    # Build everything
nix build .#lib              # Build just the library
nix build .#lgx              # Build .lgx package
nix build .#lgx-portable     # Build portable .lgx package
nix build .#install          # Build, package, and install (dev)
nix build .#install-portable # Build, package, and install (portable)

UI modules: `nix run` with logos-standalone-app

For type: ui (C++ Qt widget) and type: ui_qml (QML) modules, logos-module-builder automatically wires up apps.default so nix run . launches the module in logos-standalone-app. No separate logos-standalone-app input is needed — it is bundled inside logos-module-builder.

C++ Qt widget (mkLogosModule):

{
  inputs = {
    logos-module-builder.url = "github:logos-co/logos-module-builder";
  };

  outputs = inputs@{ logos-module-builder, ... }:
    logos-module-builder.lib.mkLogosModule {
      src = ./.;
      configFile = ./metadata.json;
      flakeInputs = inputs;
    };
}

QML-only (mkLogosQmlModule — no C++ compilation):

{
  inputs = {
    logos-module-builder.url = "github:logos-co/logos-module-builder";
  };

  outputs = inputs@{ logos-module-builder, ... }:
    logos-module-builder.lib.mkLogosQmlModule {
      src = ./.;
      configFile = ./metadata.json;
      flakeInputs = inputs;
    };
}

Then nix run . launches the module in logos-standalone-app. Dependencies listed in metadata.json are automatically bundled from their LGX packages and loaded at runtime.

See templates/ui-module, templates/ui-qml-module, and lib/mkLogosQmlModule.nix.

Features

~90% reduction in boilerplate per module
Single source of truth via metadata.json — used by Nix build and embedded into Qt plugins at compile time
Automatic CMake configuration via LogosModule.cmake
External library support (vendor pre-built or flake-input source)
Cross-platform (macOS, Linux)
Auto-resolved module dependencies from flakeInputs
Built-in LGX packaging — nix build .#lgx and nix build .#lgx-portable included automatically
Built-in install outputs — nix build .#install and nix build .#install-portable bundle and install via lgpm in one step

Documentation

Document	Description
Getting Started	Create your first module
Quick Reference	Cheat sheet for common tasks
Configuration Reference	Complete `metadata.json` specification
CMake Reference	`LogosModule.cmake` functions
Nix API Reference	`mkLogosModule` and other functions
External Libraries Guide	Wrap C/C++ libraries
Migration Guide	Migrate existing modules
Troubleshooting	Common issues and solutions

Examples

Example	Description
minimal-module	Basic module with no external dependencies
waku-module-migrated	Example migration showing 91% config reduction

Templates

Use nix flake init with our templates:

# Minimal core module
nix flake init -t github:logos-co/logos-module-builder

# C++ UI module (with nix run)
nix flake init -t github:logos-co/logos-module-builder#ui-module

# QML UI module
nix flake init -t github:logos-co/logos-module-builder#ui-qml-module

# Module with external library
nix flake init -t github:logos-co/logos-module-builder#with-external-lib

AI Assistant Skills

For AI assistants (Claude, Cursor, etc.), we provide skill files:

Skill	Description
create-logos-module	Step-by-step guide to create a new module
create-ui-module	Create a C++ Qt widget UI module
create-qml-module	Create a pure QML UI module
update-logos-module	Guide to update/modify existing modules

Architecture

logos-module-builder/
├── lib/                    # Nix library functions
│   ├── mkLogosModule.nix   # Main builder for C++ Qt plugin modules
│   ├── mkLogosQmlModule.nix # Builder for pure QML UI modules
│   ├── mkStandaloneApp.nix # apps.default for logos-standalone-app
│   ├── mkModuleLib.nix     # Library builder
│   ├── mkModuleInclude.nix # Header generator
│   ├── mkExternalLib.nix   # External library handler
│   └── parseMetadata.nix   # metadata.json parser
├── cmake/
│   └── LogosModule.cmake   # Reusable CMake module
├── templates/              # Module templates
├── examples/               # Working examples
├── docs/                   # Documentation
└── skills/                 # AI assistant skills

License

MIT

README.md

Experimental - do not use

Logos Module Builder

Overview