Skip to content

installation.md

Latest commit

 

History

History
185 lines (142 loc) · 7.92 KB

installation.md

File metadata and controls

185 lines (142 loc) · 7.92 KB
Raw
title Installation
description Install the devtools package and choose where it runs.
One package, two parts. A server part that hosts the devtools, and a browser part that sends live data from your page.

Installation

The devtools ship as one npm package, @santoshyadavdev/ng-devtools. It contains the Node side, the browser overlay, the in-page popup, the CLI and the built UI.

Prerequisites

The package declares node >=22 in its engines field. CI runs on Node.js 24. @angular/core and @angular/common 20 and newer are supported. CI runs the tests on Angular 22. pnpm, npm, yarn or bun. Any of the four. Live data comes from Angular's debug API (window.ng). Production builds remove it, so the live tabs stay empty there. Run your app in development mode while you inspect it.

Install the package

pnpm add @santoshyadavdev/ng-devtools devframe
npm install @santoshyadavdev/ng-devtools devframe
yarn add @santoshyadavdev/ng-devtools devframe
bun add @santoshyadavdev/ng-devtools devframe

MCP agent support (@devframes/agentic) is included. You don't install it separately.

Entry points

Import Use it for
@santoshyadavdev/ng-devtools/hub initNgDevtoolsHub(), the server middleware for an Express app.
@santoshyadavdev/ng-devtools/vite The Vite plugin for Analog apps.
@santoshyadavdev/ng-devtools/overlay The browser script that collects live data from your page.
@santoshyadavdev/ng-devtools/popup The floating button and panel on your page.
@santoshyadavdev/ng-devtools/http The HTTP interceptor and hydration hooks for the SSR & HTTP tab.
@santoshyadavdev/ng-devtools/config The NgDevtoolsConfig type and its defaults. See Configuration.
@santoshyadavdev/ng-devtools/devframe The devframe definition, for custom hosts.

The CLI binary

The package also installs an ng-devtools binary. It runs the devtools without your app: a local server, a static report or an MCP server. See Standalone CLI.

Pick a setup

Every setup has two parts:

  • Server part: serves the devtools UI and receives data.
  • Browser part: the overlay. It runs in your page and sends live data to the server.

Server part

Pick the tab that matches your app:

// src/server.ts
import express from 'express';
import {initNgDevtoolsHub} from '@santoshyadavdev/ng-devtools/hub';

const app = express();
const devtools = initNgDevtoolsHub({ws: false});
app.use(devtools.nodeMiddleware);
// vite.config.ts
import analog from '@analogjs/platform';
import ngDevtools from '@santoshyadavdev/ng-devtools/vite';
import {defineConfig} from 'vite';

export default defineConfig({
  plugins: [analog(), ngDevtools()],
});
# Run from the root of your Angular workspace
npx @santoshyadavdev/ng-devtools

Browser part

Load the overlay after bootstrap, in development only. The check depends on your build tool:

// src/main.ts
import {bootstrapApplication} from '@angular/platform-browser';
import {App} from './app/app';
import {appConfig} from './app/app.config';

bootstrapApplication(App, appConfig)
  .then(() => {
    if (typeof ngDevMode === 'undefined' || ngDevMode) {
      return import('@santoshyadavdev/ng-devtools/overlay');
    }
    return undefined;
  })
  .catch((err) => console.error(err));
// src/main.ts
import {bootstrapApplication} from '@angular/platform-browser';
import {App} from './app/app';
import {appConfig} from './app/app.config';

bootstrapApplication(App, appConfig).then(() => {
  if (import.meta.env.DEV) void import('@santoshyadavdev/ng-devtools/overlay');
});

The standalone CLI has no page connected, so it needs no browser part.

Configure the devtools

Everything is on by default. To turn inspectors, agent tools or actions off, or to change redaction and limits, pass options to the server part. See Configuration.

Add the Chrome extension

The Chrome extension adds a panel to Chrome DevTools. It sits on top of the Express or Vite setup. It does not replace the server part or the overlay.

Check that it works

Run ng serve for an Angular CLI app, or the Vite dev server for an Analog app. An amber button appears in the bottom-right corner of the page. The overlay adds it. Click the button. The header shows Live once the panel is connected. Go to /__devframes/ on the same server to see the devtools on their own page.

FAQ

The devtools are built on Devframe. Some setups import from devframe directly, for example initDevframe from devframe/initiate to mount only the panel. Package managers like pnpm only resolve imports of direct dependencies. Wherever your server part runs. An Express app imports the hub in server.ts, so the package must be installed where that server starts. The overlay import in main.ts only runs in development builds. Check that the app runs as a development build and that main.ts imports the overlay. A production build skips the import, so there is no button.

Where to next