Skip to content
NoctaliaNoctalia
FAQ

Guidelines

These are the basic guidelines you should follow when you want to contribute to Noctalia.

We welcome contributions of any size, bug fixes, new features, documentation improvements, themes, or configs.

Project Structure

Section titled “Project Structure”

Last updated March 09, 2026

Noctalia/
├── shell.qml                   # Main shell entry point
├── Modules/                    # UI components and panels
│   ├── Bar/                    # Status bar and widgets
│   ├── DesktopWidgets/         # Desktop widgets panel
│   ├── Dock/                   # Application dock
│   ├── Launcher/               # Application launcher
│   ├── Settings/               # Settings panel
│   ├── Panels/                 # Other panels
│   └── ...                     # Other UI modules
├── Services/                   # Backend services
│   ├── Compositor/             # Compositor
│   ├── UI/                     # UI services
│   └── ...                     # Other services
├── Widgets/                    # Reusable UI components
│   ├── NButton.qml             # Custom button component
│   ├── NTextInput.qml          # Text input component
│   └── ...                     # Other widgets
├── Commons/                    # Shared utilities
│   ├── Logger.qml              # Logging system
│   ├── Settings.qml            # Settings management
│   └── ...                     # Other utilities
├── Assets/                     # Static assets
│   ├── ColorScheme/            # Predefined color schemes
│   ├── Translations/           # Internationalization files
│   └── ...                     # Other assets
└── Scripts/                    # Development scripts

Development Guidelines

Section titled “Development Guidelines”

Setup

Section titled “Setup”

lefthook is used to format QML files. After cloning the repo, install lefthook and run lefthook install to install the pre-commit hook.

Code Organization

Section titled “Code Organization”
  1. Modular Design: Place new components in the appropriate directory:
  • Modules/ - UI panels and major components
  • Services/ - Logic and backend functionality
  • Widgets/ - Reusable UI components
  • Commons/ - Shared utilities and helpers

  1. Service-First Architecture: Implement logic in services, keep UI components lightweight and focused on presentation.

  2. Widget Reusability: Use existing widgets from Widgets/ directory before creating new ones. The N* prefixed widgets are our custom components.

Code Quality Standards

Section titled “Code Quality Standards”

  1. Follow Existing Patterns: Study how similar features are implemented and follow the same patterns.

  2. Error Handling: Implement robust error handling with proper logging using Logger.qml.

  3. Testing: Test changes with both Hyprland and Niri compositors where applicable.

  4. Small PRs: Prefer small, focused pull requests that are easier to review and test.

Code Standards

Section titled “Code Standards”

Avoid Qt5Compat: We don’t use Qt5Compat since it’s deprecated and will be removed in future Qt versions. Instead, use modern Qt6 alternatives like QtQuick.Effects (especially MultiEffect for visual effects).