Overlay System

🎨 Overlay System

What are Overlays?

The Overlay System in Nexo Maker allows expansion developers to create global, persistent UI components that run outside of any specific project context. These overlays appear on top of the main application and remain visible across all routes and project changes.

Key Characteristics

• Global Scope - Overlays run independently of project navigation

• Persistent State - Data persists across route changes and app restarts

• Event System - Can react to keyboard shortcuts and global events

• Interactive UI - Support for draggable, clickable components

• Background Services - Can run invisible background processes

How Overlays Work

Overlays are registered as background modules and are loaded when the application starts. They:

1. Load globally inside the APP scope

2. Persist across navigation - remain active when changing routes

3. Share state using the global state system

4. Communicate through the notification and event system

5. Run continuously until the application closes

Registration

Register overlays using registerBackgroundModule in your expansion's main.js:

module.exports.init = async () => {
  const nm = api.nexomaker;
  
  nm.registerBackgroundModule("overlay-id", __dirname + "/path/to/Overlay.jsx", {
    zIndex: 1500,
    props: { /* optional props */ }
  });
};

Component Structure

Overlay components use the standard Nexo Maker modular format:

module.exports = ({ useState, useEffect, useRef, useGlobalState, api, usePlaceholders }) => {
  // Component logic here
  
  return React.createElement('div', {
    style: { position: 'fixed', /* positioning styles */ }
  }, 'Overlay content');
};

Background Code Without UI

Overlays can also run background code without any visible UI by returning an empty fragment:

module.exports = ({ useState, useEffect, useGlobalState, api }) => {
  // Background service logic
  useEffect(() => {
    const interval = setInterval(() => {
      // Perform background tasks
      console.log('Background service running...');
    }, 5000);
    
    return () => clearInterval(interval);
  }, []);
  
  // Return empty fragment for no UI
  return React.createElement(<></>);
};

State Management

Overlays use useGlobalState for persistent data that survives route changes:

const [isVisible, setIsVisible] = useGlobalState('overlayVisible', true);
const [position, setPosition] = useGlobalState('overlayPosition', { x: 100, y: 100 });

Common Use Cases

Status Displays

Show system information, project status, or monitoring data that users need to see at all times.

Quick Actions

Provide shortcuts to frequently used tools or actions without navigating to specific pages.

Notifications

Display alerts, progress indicators, or status messages that persist across the application.

Background Services

Run invisible processes that monitor events, sync data, or perform periodic tasks. These can return React.createElement(React.Fragment) to run without any UI.

Developer Tools

Create debugging interfaces, performance monitors, or development utilities.

Positioning and Styling

Overlays typically use:

• position: fixed for absolute positioning

• High zIndex values (1500+) to appear above other content

• Careful positioning to avoid interfering with the main UI

• Responsive design considerations for different screen sizes

Lifecycle

1. Registration - Overlay is registered in expansion's main.js

2. Loading - Component is loaded when application starts

3. Mounting - React component mounts and initializes state

4. Runtime - Overlay runs continuously, responding to events

5. Persistence - State is maintained across navigation

6. Cleanup - Component unmounts only when application closes