Skip to content

installation.md

Latest commit

 

History

History
256 lines (202 loc) · 12.2 KB

installation.md

File metadata and controls

256 lines (202 loc) · 12.2 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, @pangular-inspector/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 tests Node.js 22 and 24. @angular/core and @angular/common 20 and newer are supported, with no upper bound. See Tested versions. 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.

Tested versions

The peer range is @angular/* >=20 with no upper bound. CI tests these versions:

Angular Node.js What runs When
20.0 (lowest supported) 22 The page-side tests against a real Angular app Every push to main, and weekly
21 (latest 21.x) 22 The page-side tests against a real Angular app Every push to main, and weekly
22 (latest 22.x) 22 The page-side tests, including Signal Forms Every push to main, and weekly
22 (repository version) 24 Every package and panel test, the type checks and axe Every pull request and push to main
Newest the ranges allow 24 A fresh Angular CLI app and a fresh Analog app with the package installed Weekly

Some features need a later Angular release than 20.0. The inspector pages list them, for example abort and probe (20.2) and the live signal graph (20.1). The Signal Forms tests run on Angular 22 and later, where Signal Forms are stable.

Install the package

pnpm add @pangular-inspector/devtools devframe
npm install @pangular-inspector/devtools devframe
yarn add @pangular-inspector/devtools devframe
bun add @pangular-inspector/devtools devframe

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

Entry points

Import Use it for
@pangular-inspector/devtools/hub initPangularHub(), the server middleware for an Express app.
@pangular-inspector/devtools/vite The Vite plugin for Analog apps.
@pangular-inspector/devtools/overlay The browser script that collects live data from your page.
@pangular-inspector/devtools/overlay-angular-native The overlay for an Angular Native app. See Angular Native.
@pangular-inspector/devtools/overlay-nativescript The overlay for a NativeScript Angular app. See NativeScript.
@pangular-inspector/devtools/popup The floating button and panel on your page.
@pangular-inspector/devtools/http The HTTP interceptor and hydration hooks for the SSR & HTTP tab.
@pangular-inspector/devtools/config The PangularConfig type and its defaults. See Configuration.
@pangular-inspector/devtools/devframe The devframe definition, for custom hosts.

The CLI binary

The package also installs a pangular 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 {initPangularHub} from '@pangular-inspector/devtools/hub';

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

export default defineConfig({
  plugins: [analog(), pangular()],
});
# Run from the root of your Angular workspace
npx @pangular-inspector/devtools
// proxy.conf.json
{
  "/__pangular": {
    "target": "http://localhost:9999",
    "pathRewrite": {"^/__pangular": ""},
    "ws": true
  }
}

A client-only app (no SSR) has no server of its own to mount the devtools in. See Client-only Angular CLI app.

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('@pangular-inspector/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('@pangular-inspector/devtools/overlay');
});

The standalone CLI on its own has no page connected, so it needs no browser part. Behind the ng serve proxy of a client-only app it does, like any other setup.

Client-only Angular CLI app

An app created with ng new --ssr=false only runs ng serve. Run the standalone CLI next to it, and let ng serve forward /__pangular/ to the CLI. The overlay and the popup look for the devtools at /__pangular/ on the page's own origin, so they find the CLI there.

Run npx pangular dev --port 9999 from the root of your workspace. It serves the panel, the connection and the WebSocket at the root of port 9999. Save the proxy.conf.json above next to angular.json. It strips the /__pangular prefix, and "ws": true forwards the WebSocket the overlay and the panel connect over. Set proxyConfig in the serve options of angular.json, or run ng serve --proxy-config proxy.conf.json. Import the overlay in main.ts, as in the Angular CLI tab above. When your app connects, the CLI prints a code and a link like http://localhost:9999/#devframe_otp=123456. That link only trusts port 9999. Open the same code on your app's origin instead, http://localhost:4200/__pangular/#devframe_otp=123456. If the panel was already open, reload your app. 
// angular.json (excerpt)
{
  "projects": {
    "my-app": {
      "architect": {
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          }
        }
      }
    }
  }
}

The full-page panel is at /__pangular/ on your app's origin.

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