Project Structure

Project Structure#

Warning

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

Directory Layout#

After running nextgen create project, the project directory has the following layout:

my-dashboards/
├── package.json              # npm scripts and dependency declarations
├── rsbuild.config.ts         # Build configuration (do not change)
├── tsconfig.json             # TypeScript config (extends core base config)
├── biome.json                # Linting and formatting config (extends core config)
├── index.html                # HTML shell entry point
├── .env                      # Credentials and port settings (never commit)
├── .npmrc                    # npm registry routing for @squirro packages
├── CLAUDE.md                 # AI-assisted development guidelines
├── .gitignore                # Pre-configured to exclude .env and node_modules
└── src/
    ├── manifest.ts           # Extension manifest — your main configuration file
    ├── bootstrap.ts          # Module Federation bootstrap (do not edit)
    ├── main.tsx              # Standalone dev preview only (not loaded in production)
    ├── dev-tools.ts          # Translation key dev overlay (do not edit)
    ├── index.css             # Global styles for your extension
    ├── utils.ts              # cn() utility for combining class names
    └── dashboards/
        └── Analytics.tsx     # Your dashboard components live here

File

Editable

Notes

src/dashboards/*.tsx

Yes

All dashboard UI lives here.

src/manifest.ts

Occasionally

Managed by the CLI. Edit manually only to reorder dashboards or change an icon.

src/index.css

Yes

Global extension styles.

.env

Yes

Update credentials or ports. Use nextgen config for interactive editing.

package.json

Occasionally

Only when adding approved third-party libraries.

rsbuild.config.ts

Rarely

Advanced Module Federation customization only.

CLAUDE.md

Occasionally

AI coding guidelines. Adjust if using Claude Code.

bootstrap.ts

No

Module Federation async bootstrap entry. Do not modify.

main.tsx

No

Standalone dev preview entry. Not loaded in production. The CLI updates it automatically when you add or remove dashboards.

dev-tools.ts

No

Translation key development overlay. Do not modify.

Key Files#

src/manifest.ts#

The manifest is the contract between your extension and the host application. It declares every dashboard your extension provides. The CLI manages it when you run nextgen create dashboard or nextgen remove dashboard, but you can also edit it manually.

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

declare const NEXTGEN_CORE_VERSION: string;

const manifest: ExtensionManifest = {
  name: 'my-dashboards',                   // unique identifier for your extension
  platformVersion: NEXTGEN_CORE_VERSION,    // injected at build time by the CLI
  dashboards: [
    {
      id: 'analytics',
      title: 'Analytics',
      icon: 'bar-chart-3',
      route: 'analytics',
      component: () => import('./dashboards/Analytics'),
    },
  ],
};

export default manifest;

For the full manifest format reference, see the The Extension Manifest page.

src/main.tsx#

main.tsx is the entry point for the standalone development preview. When nextgen dev starts the extension server, this file renders a minimal React application into index.html so you can browse your dashboards in a browser without a live Squirro instance.

Important

main.tsx does not run in production. When the host application loads your extension, it imports only src/manifest.ts via Module Federation. Any initialization code placed in main.tsx is silently absent at runtime.

Place startup logic such as provider setup or global state initialization inside your dashboard components, not in main.tsx.

The CLI manages this file. It adds and removes route entries automatically when you run nextgen create dashboard or nextgen remove dashboard. You do not need to edit it manually.

src/dashboards/#

This directory contains your React components. Each file corresponds to one dashboard. The CLI creates a starter file when you run nextgen create dashboard.

Every dashboard component receives a projectId prop, injected automatically by the host:

export default function Analytics({ projectId }: { projectId: string }) {
  // use projectId to fetch data for the active project
}

src/index.css#

Global styles loaded for the entire extension. The host theme tokens for colors, typography, and spacing are already available. Add extension-specific styles here:

@import '@squirro/nextgen-core/styles/theme.css';

/* your custom styles below */

Tailwind utility classes work out of the box without any additional setup.

.env#

Contains credentials and port settings.

Warning

Never commit this file. It is already included in .gitignore.

# Squirro API configuration
SQUIRRO_API_URL=https://your-instance.example.com
SQUIRRO_TOKEN=your-refresh-token

# Optional: override defaults
# EXTENSION_PORT=3001
# DEV_PROXY_PORT=5555

Restrict the file permissions so that only your user account can read it:

chmod 600 .env

To update these values interactively, run nextgen config.

.npmrc#

Routes @squirro-scoped package installs to GitHub Packages. This file contains only registry configuration and no auth tokens, so it is safe to commit:

@squirro:registry=https://npm.pkg.github.com

rsbuild.config.ts#

The entire build configuration is a single line:

import { createExtensionConfig } from '@squirro/nextgen-core/config';

export default createExtensionConfig({ name: 'my-dashboards' });

createExtensionConfig sets up Module Federation, Tailwind CSS, TypeScript, CORS for the development server, and all other build settings. You rarely need to modify this file.

Updating Dependencies#

The @squirro/nextgen-core and @squirro/nextgen-cli packages are installed into node_modules/ during project creation. They are pinned to the version that was current when you created the project.

Both packages are published to GitHub Packages under the @squirro scope. Because your project .npmrc already routes that scope to the GitHub Packages registry, you can update them with standard npm install commands.

To update both packages inside an existing project:

npm install @squirro/nextgen-core@latest
npm install --save-dev @squirro/nextgen-cli@latest

After updating, restart nextgen dev or run nextgen build for the changes to take effect.

To update the globally installed CLI (used when creating new projects):

npm install -g @squirro/nextgen-cli@latest
Contents