@nngforge/core

TypeScript interfaces, DI tokens, and integration models for the DashForge embeddable dashboard builder.

This package is the free, open integration layer for DashForge — an embeddable drag-and-drop dashboard and PDF report builder for Angular 19+. It contains:

• All serializable config models (DashboardConfig, WidgetConfig, QueryConfig, ThemeConfig, …)
• Angular DI tokens for pluggable storage, credential vault, audit logging, auth, and theming
• No Angular components — the builder UI and viewer ship via the commercial license

What's in this package

@nngforge/core
├── Models (serializable interfaces)
│   ├── DashboardConfig, LayoutConfig, WidgetConfig, WidgetType
│   ├── 16 widget param types (LineChartParams, BarChartParams, PieChartParams, …)
│   ├── QueryConfig + 6 connector param types (REST, WebSocket, SQL, Sheets, CSV, Mock)
│   ├── ThemeConfig, ReportConfig, FilterConfig
│   └── WidgetStyle, TableColumn, GaugeParams, HeatmapParams, …
│
├── Storage abstraction
│   ├── IConfigStorage interface
│   └── CONFIG_STORAGE injection token
│
├── Credential vault
│   ├── ICredentialVault interface
│   ├── CREDENTIAL_VAULT injection token
│   ├── NullCredentialVault (default, uses inline values)
│   └── warnInlineCredential() (dev-mode deprecation helper)
│
├── Auth
│   ├── AUTH_TOKEN injection token
│   └── dashforgeAuthInterceptor (HttpInterceptorFn)
│
├── Client theming
│   ├── DASHFORGE_CLIENT_THEME injection token
│   ├── ClientVarMap type
│   └── clientThemeFromCSSVars() utility
│
└── Audit logging
    ├── IAuditLogger interface
    ├── CredentialAuditEvent type
    ├── AUDIT_LOGGER injection token
    └── ConsoleAuditLogger (default implementation)

Installation

npm install @nngforge/core

Peer dependencies (must already be in your project):

@angular/core >= 19
@angular/common >= 19
@angular/forms >= 19
@angular/material >= 19
@ngrx/signals >= 19
echarts >= 5
ngx-echarts >= 19
rxjs >= 7

Usage — configure DashForge providers

In app.config.ts:

import {
  CONFIG_STORAGE,
  CREDENTIAL_VAULT,
  AUDIT_LOGGER,
  AUTH_TOKEN,
  NullCredentialVault,
  ConsoleAuditLogger,
  dashforgeAuthInterceptor,
} from '@nngforge/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
  providers: [
    // Required: tell DashForge where to load/save dashboard configs
    { provide: CONFIG_STORAGE, useClass: YourConfigStorageService },

    // Recommended: resolve credential IDs at runtime (keep secrets out of config JSON)
    { provide: CREDENTIAL_VAULT, useClass: NullCredentialVault },

    // Optional: log credential access to your audit system
    { provide: AUDIT_LOGGER, useClass: ConsoleAuditLogger },

    // Optional: inject a Bearer token for all DashForge HTTP requests
    { provide: AUTH_TOKEN, useFactory: () => inject(YourAuthService).token },
    provideHttpClient(withInterceptors([dashforgeAuthInterceptor])),
  ],
};

Implement IConfigStorage

DashForge uses IConfigStorage to load and save dashboard configs. Replace the default localStorage implementation with your own backend:

import { Injectable } from '@angular/core';
import { IConfigStorage, DashboardConfig } from '@nngforge/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class ApiConfigStorage implements IConfigStorage {
  constructor(private http: HttpClient) {}

  getAll(): Observable<DashboardConfig[]> {
    return this.http.get<DashboardConfig[]>('/api/dashboards');
  }

  get(id: string): Observable<DashboardConfig | null> {
    return this.http.get<DashboardConfig>(`/api/dashboards/${id}`);
  }

  save(config: DashboardConfig): Observable<DashboardConfig> {
    return this.http.put<DashboardConfig>(`/api/dashboards/${config.id}`, config);
  }

  delete(id: string): Observable<void> {
    return this.http.delete<void>(`/api/dashboards/${id}`);
  }
}

Implement ICredentialVault

Keep API keys, bearer tokens, and database credentials out of dashboard config JSON:

import { Injectable } from '@angular/core';
import { ICredentialVault } from '@nngforge/core';

@Injectable({ providedIn: 'root' })
export class BackendVault implements ICredentialVault {
  constructor(private secrets: SecretsService) {}

  resolve(credentialId: string): string | null {
    return this.secrets.get(credentialId) ?? null;
  }
}

In your dashboard config, use credentialId: 'my-api-key' instead of authToken: 'sk-...'.

Map your design system colors to DashForge

import { DASHFORGE_CLIENT_THEME, clientThemeFromCSSVars } from '@nngforge/core';

providers: [
  {
    provide: DASHFORGE_CLIENT_THEME,
    useValue: clientThemeFromCSSVars({
      primary:    '--brand-primary',
      secondary:  '--brand-secondary',
      background: '--surface-background',
      surface:    '--surface-card',
      text:       '--text-primary',
      textMuted:  '--text-secondary',
      border:     '--border-default',
    }),
  },
],

Links

• Live demo: demo.dashforge.dev
• Docs: dashforge.dev/docs
• Integration guide: dashforge.dev/docs/integration
• Security: dashforge.dev/security
• Commercial license (builder UI + viewer + widgets): dashforge.dev/pricing
• GitHub: github.com/nng-dev/dashforge

License

MIT — see LICENSE.

The builder UI, viewer, and widget components are commercially licensed.
See dashforge.dev/pricing for details.