The Extension Manifest

The Extension Manifest#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

The manifest is the central configuration file for your extension. It declares what dashboards your extension provides, how they appear in the sidebar, and optionally supplies translated strings.

File: src/manifest.ts

Note

You rarely need to edit this file by hand. The CLI manages it automatically: nextgen create dashboard adds entries, nextgen remove dashboard removes them, and nextgen translations init wires up translations. The reference below covers what the CLI generates and the rare cases where manual adjustments are needed, such as reordering dashboards or changing an icon.

Full Type Reference#

import type { ExtensionManifest } from '@squirro/nextgen-core';

interface ExtensionManifest {
  /** Unique identifier for this extension. Used in translations and internal naming. */
  name: string;

  /**
   * Semver of @squirro/nextgen-core the extension was built against.
   * Injected automatically at build time by the CLI — you do not set this manually.
   * The host compares it against its own version and logs a warning on mismatch.
   */
  platformVersion: string;

  /** The list of dashboards this extension provides. */
  dashboards: ExtensionDashboard[];

  /**
   * Optional translations.
   * Keys without ':' go into the 'ext-{name}' namespace (your own strings).
   * Keys with ':' (e.g. 'chat:inputPlaceholder') override the matching host key.
   */
  translations?: Record<string, Record<string, string>>;
}

interface ExtensionDashboard {
  /** Unique identifier within this manifest. Doubles as the route ID. */
  id: string;

  /** Display name shown in the sidebar navigation. */
  title: string;

  /** Lucide icon name in kebab-case (e.g. 'bar-chart-3'). */
  icon: string;

  /** URL slug — no leading slash, lowercase kebab-case recommended. */
  route: string;

  /** Lazy import returning the dashboard React component. */
  component: () => Promise<{ default: ComponentType<{ projectId: string }> }>;
}

A Complete Manifest Example#

import type { ExtensionManifest } from '@squirro/nextgen-core';

declare const NEXTGEN_CORE_VERSION: string;

if (import.meta.env.DEV) {
  void import('./dev-tools');
}

const manifest: ExtensionManifest = {
  name: 'my-dashboards',
  platformVersion: NEXTGEN_CORE_VERSION,
  dashboards: [
    {
      id: 'analytics',
      title: 'Analytics',
      icon: 'bar-chart-3',
      route: 'analytics',
      component: () => import('./dashboards/Analytics'),
    },
    {
      id: 'reports',
      title: 'Monthly Reports',
      icon: 'file-text',
      route: 'reports',
      component: () => import('./dashboards/Reports'),
    },
  ],
};

export default manifest;

Dashboard Fields#

The id Field#

A string that uniquely identifies the dashboard within your extension. By default, the CLI sets it to the same value as route. It is used internally and does not need to be changed.

The title Field#

The text label shown in the sidebar navigation. Keep it short. The sidebar has limited horizontal space.

The icon Field#

A Lucide icon name in kebab-case. Browse all available icons at lucide.dev/icons.

Common choices:

Icon name

Use case

layout-dashboard

General dashboard

bar-chart-3

Analytics and charts

file-text

Reports and documents

users

People and accounts

search

Search results

settings

Configuration

database

Data and storage

activity

Activity and monitoring

map

Geographic data

calendar

Scheduling and timeline

If the icon name is invalid or unknown, the host renders nothing in that slot. No crash occurs.

The route Field#

The URL path segment for this dashboard. The full URL takes the form:

/:projectId/dashboard/{route}

Rules:

  • Must be unique across all dashboards in the manifest.

  • No leading or trailing slashes.

  • Lowercase kebab-case is strongly recommended.

  • Treat routes as permanent. Renaming a route breaks saved bookmarks and deep links.

The component Field#

A function returning a dynamic import. That approach splits the dashboard bundle so it is only fetched when the user navigates to that dashboard, not on application startup.

component: () => import('./dashboards/Analytics'),

The import must resolve to a file with a default export matching the dashboard component signature. For more information, see the Building Dashboard Components page.

Dashboard Ordering#

Dashboards appear in the sidebar in the order they are declared in the dashboards array. Reorder the array to change the sidebar order.

Translations#

The translations field in the manifest lets your extension provide localized strings and override host UI text. Run nextgen translations init to set it up. The CLI handles everything automatically.

For more information, see the Translations page.

CLI Management vs Hand-Editing#

The CLI manages the manifest automatically. In most workflows, you will never need to edit this file by hand:

  • nextgen create dashboard adds a dashboard entry and creates the component file.

  • nextgen remove dashboard removes a dashboard entry and deletes the component file.

  • nextgen translations init adds the translations import and field.

For the rare cases where you do need to edit manually, such as reordering dashboards or changing an icon or route, the CLI and hand-edits coexist without conflict as long as the basic structure remains intact: a dashboards array with objects containing id, title, icon, route, and component.

Tip

After hand-editing the manifest, verify it compiles by running npx tsc --noEmit.

Contents