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 neo-ui create bundle my-dashboards, the bundle 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)
├── components.json           # shadcn/ui component config (for adding components)
├── 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
├── .claude/
│   └── skills/               # Squirro skills for Claude Code (API, components, translations, deploy, and more)
└── src/
    ├── manifest.ts           # Bundle manifest, your main configuration file
    ├── theme.ts              # Brand theme: colors, logo, favicon (edit to brand)
    ├── 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 bundle
    ├── env.d.ts              # Ambient TypeScript declarations (do not edit)
    ├── utils.ts              # cn() utility for combining class names
    └── dashboards/
        └── Analytics.tsx     # Your dashboard components live here

What to Edit#

File

Editable

Notes

src/dashboards/*.tsx

Yes

All dashboard UI lives here.

src/theme.ts

Yes

Brand colors, logo, and favicon. Edit to match the customer brand.

src/manifest.ts

Occasionally

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

src/index.css

Yes

Global bundle styles.

.env

Yes

Update credentials or ports. Use neo-ui 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 bundle and the host application. It declares every dashboard your bundle provides. The CLI manages it when you run neo-ui create dashboard or neo-ui remove dashboard, but you can also edit it manually.

import { defineBundleManifest } from '@squirro/nextgen-core';
import theme from './theme';

declare const NEXTGEN_CORE_VERSION: string;

export default defineBundleManifest({
  name: 'my-dashboards',                   // unique identifier for your bundle
  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'),
    },
  ],
  theme,                                    // brand defaults from src/theme.ts
  isBrandingSource: false,                   // set true on exactly one bundle per tenant
});

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

src/main.tsx#

main.tsx is the entry point for the standalone development preview. When neo-ui dev starts the bundle 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 bundle, 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 neo-ui create dashboard or neo-ui 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 neo-ui 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 bundle. The host theme tokens for colors, typography, and spacing are already available. Add bundle-specific styles here:

@import "tailwindcss";
@import '@squirro/nextgen-core/styles/theme.css';
/* @source is a Tailwind filesystem glob, so it needs a relative path */
@source "../node_modules/@squirro/nextgen-core/dist";

/* your custom styles below */

The @import "tailwindcss"; line is what makes Tailwind utility classes work out of the box. The theme import provides the host design tokens, and @source lets Tailwind scan the host components so their classes are not purged.

.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
# BUNDLE_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 neo-ui 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 { createBundleConfig } from '@squirro/nextgen-core/config';

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

createBundleConfig 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/neo-ui packages are installed into node_modules/ during bundle creation. They are pinned to the version that was current when you created the bundle.

To update both @squirro package versions and reinstall, run a single command:

neo-ui upgrade

After updating, restart neo-ui dev or run neo-ui build for the changes to take effect.


Contents