LobsterBoard

LobsterBoard is organized into a Node.js server environment with a web-based dashboard builder. Key directories include:

• server.cjs: The Node.js server entry point.
• app.html: The main dashboard builder interface.
• config.json: Stores your saved dashboard layouts.
• js/: Contains the core logic, including builder.js (editor logic), widgets.js (widget definitions), and templates.js (template management).
• templates/: Holds the template gallery and individual template folders.
• pages/: A directory for auto-discovered custom pages.

LobsterBoard allows you to extend the dashboard with custom pages. Pages are auto-discovered by the server if they follow a specific directory structure within the pages/ folder. Each page requires a page.json for metadata and an index.html for the UI. You can optionally include an api.cjs for server-side logic.

Directory Structure:

pages/
└── my-page/
    ├── page.json       # Metadata (title, icon, order)
    ├── index.html      # Page UI
    └── api.cjs         # Optional: server-side API routes

After adding a new page folder, restart the server to see it in the navigation menu.

When referencing scripts, stylesheets, or images in your index.html, always use absolute paths (starting with /). Using relative paths may cause assets to fail to load depending on how the URL is accessed.

<!-- ✅ Correct: absolute paths -->
<script src="/pages/my-page/script.js"></script>
<link rel="stylesheet" href="/pages/my-page/style.css">

<!-- ❌ Wrong: relative paths may break -->
<script src="script.js"></script>

To include the standard LobsterBoard navigation bar in your custom page, add a <nav> element with the ID page-nav and include the shared navigation script in your index.html.

The script /pages/_shared/nav.js fetches /api/pages to render links for all enabled pages and automatically highlights the current page.

<nav id="page-nav"></nav>
<!-- ... your page content ... -->
<script src="/pages/_shared/nav.js"></script>

To manually create a page, set up a folder within pages/ containing the following files:

• page.json (Required): Contains page metadata.
• index.html (Required): The HTML structure of your page.
• api.cjs (Optional): Server-side API routes. Note: You must use the .cjs extension because the LobsterBoard package is configured as an ES module ("type": "module").
• style.css (Optional): Custom styles for the page.

pages/
└── my-page/
    ├── page.json       # Required: metadata
    ├── index.html      # Required: page HTML
    ├── api.cjs         # Optional: server-side API routes (use .cjs extension)
    └── style.css       # Optional: additional styles

You can install LobsterBoard via npm or by cloning the repository directly. Once installed, run the server using node server.cjs.

To use the dashboard:

1. Open http://localhost:8080 in your browser.
2. Press Ctrl+E to enter edit mode.
3. Drag widgets from the sidebar onto the canvas.
4. Click 💾 Save to persist your layout.

# Option 1: Install via npm
npm install lobsterboard
cd node_modules/lobsterboard
node server.cjs

# Option 2: Clone the repository
git clone https://github.com/Curbob/LobsterBoard.git
cd LobsterBoard
npm install
node server.cjs

When importing a template into your LobsterBoard instance, you have two options:

• Replace: This will overwrite your entire current dashboard with the template's configuration.
• Merge: This adds the template's widgets below your existing widgets. LobsterBoard will automatically offset the positions to prevent overlap.

To create a template manually, create a new directory inside the templates/ folder. Each template must contain a meta.json file and a config.json file. An optional preview.png is recommended for the template registry.

Directory Structure:

templates/
└── my-template/
    ├── meta.json       # Template metadata
    ├── config.json     # Dashboard configuration
    └── preview.png     # Preview screenshot (optional)