Overview

Warning

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

The Project Neo bundle system lets development teams build custom dashboards that load into the Project Neo host application at runtime. A bundle is a separate React and TypeScript project with its own repository, dependencies, and build pipeline. It installs @squirro/neo-core as a library, which provides build configuration, shared types, and UI components. The @squirro/neo-ui tool scaffolds the project and handles development and builds. At runtime, the bundle connects to the host application through Module Federation, a webpack and rspack feature that allows independently built applications to share code at runtime.

Why This Architecture

Benefit	Details
Independent development and deployment	Bundles are separate projects with their own repository, CI pipeline, and release cycle. You can build, test, and deploy a bundle without coordinating with the Squirro core team or waiting for a host release.
No host changes needed	Adding, renaming, or removing dashboards is a bundle-side operation. The host discovers bundles at runtime. No code changes or redeployment of the core application are required.
Per-project customization	Different Squirro projects can load different bundles. A legal team can have a legislation dashboard while a research team has an analytics dashboard, each configured via the frontend.ui-bundle project setting.
Isolation	Bundle bugs cannot crash the core application. Bundles cannot inject global CSS, access host internals, or modify core application logic. The host remains stable regardless of what bundles do.
Native feel	Unlike iframe-based approaches, bundles share the same React instance, router, theme, and navigation as the host. Dashboards look and behave like built-in features.
Lazy loading	Dashboard code is only fetched when the user navigates to it. Bundles add no overhead to the initial application load.
Familiar tooling	Bundles use standard React and TypeScript with npm tooling. There is no proprietary framework to learn.

What You Can Build

• Custom dashboards

  Full-page React components with access to Squirro data, shared UI components, and the active project context. Each dashboard appears automatically in the Project Neo sidebar navigation.

• Translation overrides

  Customize any text in the core Project Neo interface per language, without modifying host code. That means bundles can tailor the entire application experience, not just the dashboards they add. For more information, see the Translations page.

What You Cannot Do

Bundles have defined boundaries to keep the core product stable:

• You cannot override or modify built-in widgets.

• You cannot inject global CSS that affects the host interface.

• You cannot hook into core widget internals.

• You cannot modify core application logic.

If a use case requires changes to core features, that is a product request.

How It Works

When a user opens a Squirro project, the Project Neo host checks whether the project has a bundle configured via the frontend.ui-bundle project setting. If it does, the host fetches the bundle manifest: a TypeScript file that declares the bundle dashboards, including their title, icon, URL route, and the React component to render. The host then:

1. Adds navigation entries to the sidebar for each dashboard.

2. Creates dynamic routes so each dashboard is accessible at its URL.

3. Lazy-loads the dashboard component on demand when the user navigates to it.

No host code changes are required. Adding, renaming, or removing dashboards is handled entirely within the bundle project.

The host and bundle are deployed independently. You upload a bundle to the Squirro backend and associate it with specific projects through the frontend.ui-bundle project setting, so each project loads only the bundle assigned to it. When the host loads a bundle manifest, it deduplicates shared libraries such as React, the router, and state management, loading them once, while all other bundle code stays isolated from the host and from other bundles.

Development Workflow

The following commands cover the full bundle development lifecycle:

neo-ui create bundle         # Scaffold a complete bundle project
neo-ui create dashboard      # Add a dashboard to the project
neo-ui dev                   # Start local development servers
neo-ui build                 # Build the bundle for production deployment

For a step-by-step walkthrough, see the Quick Start page.

Package Overview

Package	Description
@squirro/neo-ui	The neo-ui CLI tool for project scaffolding, development server, build, and deployment.
@squirro/neo-core	Everything a bundle imports at runtime, split into the entry points below.

Both packages are published on the public npm registry.

@squirro/neo-core is a single package with several entry points. Import from the subpath rather than from the root, so your bundle only pulls in what it uses:

Import path	What it provides	Guide
@squirro/neo-core	defineBundleManifest, defineThemeManifest, and the manifest and theme types.	The Bundle Manifest
@squirro/neo-core/config	createBundleConfig, the Rsbuild configuration factory, along with sharedDependencies, validateDependencies, the default development ports, and the tsconfig.extension.json and biome.extension.json presets.	Project Structure
@squirro/neo-core/components	Host-themed UI primitives such as buttons, forms, dialogs, and charts.	Styling and Components
@squirro/neo-core/items	Item widgets: item cards, item lists, and the item detail view with the default PDF viewer.	Building Dashboard Components
@squirro/neo-core/chat	The embeddable chat widget (ChatProvider and ChatPanel) and the stream primitives beneath it.	The Chat Widget
@squirro/neo-core/api	useSquirroApi(), the typed and authenticated client for items, facets, files, conversations, and groups.	Squirro API
@squirro/neo-core/citations	Helpers to parse and render GenAI answer citations, including CitationBadge and parseSquirroReference. Use them rather than writing your own parsing.	None
@squirro/neo-core/export	exportAsDocx and exportAsPDF for plain-text exports. The @squirro/neo-core/export/markdown-to-docx subpath holds the rich Markdown to DOCX engine, kept separate because it pulls in heavy dependencies.	None
@squirro/neo-core/utils	cn, getInitials, and getRelativeTimeLabel.	None
@squirro/neo-core/version	evaluateCompat, which reports whether a bundle is compatible with the host version it is loaded into.	Building and Deploying

Everything a bundle can import from @squirro/neo-core is documented visually in the component catalog at neo-catalog.squirro.com, with live previews, prop tables, and copy-paste import examples. For more information, see the Styling and Components page.