---
title: Angular CLI and Express
description: Mount the devtools hub in the Express server of an Angular SSR app.
---
Mount the devtools hub in your server.ts, load the overlay in main.ts, and open the panel from a button on your page.
# Angular CLI and Express
In an *Angular app with server-side rendering, the devtools run inside your Express server. You add a middleware on the server and load the overlay in the browser.
This setup mounts the devtools in the Express server.ts that Angular SSR generates. For an Analog app, follow Vite and Analog instead. For a server on Hono, h3 or Fastify, follow Hono, h3 and Fastify.
## Setup at a glance
Add @pangular-inspector/devtools as a dependency, because server.ts imports it. See Installation.
Add initPangularHub() to server.ts, before your other routes.
Import the overlay in main.ts, in development only.
Start the app in development mode and click the Pangular Inspector button in the corner of the page.
## Mount the hub
### Add the middleware
```ts {3,6-7}
// 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);
```
The full-page viewer is at `http://localhost:4000/__devframes/`. The hub is built on [`@devframes/hub`](https://github.com/devframes/devframe), so other devframe tools can join the same dock.
The Angular CLI bundles `server.ts`, but not the hub. `initPangularHub()` loads the hub's server code from `node_modules/@pangular-inspector/devtools` when it starts, so the hub and its dependencies resolve from the package as they do under Vite, with any package manager. This needs Node.js 22.12 or later. On an older Node.js the hub logs why and turns itself off, and your server runs on without it. When the hub is off, as in production, nothing is loaded.
### Middleware order
Mount the middleware before `express.static` and the Angular SSR handler, so the devtools routes answer first.
```ts
// src/server.ts
const app = express();
const devtools = initPangularHub({ws: false});
app.use(devtools.nodeMiddleware); // devtools first
app.use(express.static(browserDistFolder, {index: false}));
app.use((req, res, next) => {
angularApp
.handle(req)
.then((response) => (response ? writeResponseToNodeResponse(response, res) : next()))
.catch(next);
});
```
The middleware only handles requests under its base path (`/__devframes/` by default). Everything else goes to the next handler.
### Pick a transport
The browser talks to the hub over server-sent events or a WebSocket. Pick one with the `ws` option:
```ts group="transport" name="Server-sent events" active
// src/server.ts
const devtools = initPangularHub({ws: false});
```
```ts group="transport" name="WebSocket side-car"
// src/server.ts
const devtools = initPangularHub({ws: {sidecar: true}});
```
With `ws: false` there is no WebSocket, and the browser connects over SSE on the same port. It is the simplest choice: every request goes through your Express server, including under `ng serve`.
With `ws: {sidecar: true}`, the WebSocket runs on its own port. The hub takes the first free port from 9777 to 9877, whatever port your app uses, and advertises it in `__connection.json`. Two apps started at once get different ports from that range.
If a firewall or a container only lets known ports through, pin the port with `ws: {port}`. The hub then listens on that port only, and fails to start when it is taken, instead of moving to another one. To keep it next to the app's port, derive it from the port the app listens on:
```ts
// src/server.ts
const port = Number(process.env['PORT'] ?? 4000);
const devtools = initPangularHub({ws: {port: port + 1}});
```
To use no second port at all, run the WebSocket on the app's own server: leave out `ws` and pass the server that `app.listen()` returns to `devtools.attach()`. Upgrades to `__ws` then go to the hub, behind the same request gate as `nodeMiddleware`. Under `ng serve`, `server.ts` doesn't start a server of its own, so use `ws: false` or a side-car there.
```ts
// src/server.ts
const server = app.listen(port);
devtools.attach(server);
```
### Rebuilds under `ng serve`
`ng serve` runs `server.ts` again after a rebuild that changes the server output. The process keeps one hub per `base`, so each new `initPangularHub()` call closes the hub from the run before, along with its side-car port. The MCP token stays the same: the hub keeps it in a file. See [Send a token](../agents/mcp-server.md#send-a-token).
### Hub options
`initPangularHub()` accepts the options of `initHub()` from `@devframes/hub`, apart from `devframes` and `ui`. These are the ones you are most likely to set:
| Option | Default | What it does |
| ---------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base` | `'/__devframes/'` | Where the hub is mounted. The devtools panel lives at `pangular/`. |
| `ws` | | `false` uses server-sent events only. `{sidecar: true}` runs the WebSocket on its own port, the first free one from 9777. `{port: 4001}` pins that port. See [Pick a transport](#pick-a-transport). |
| `enabled` | on unless this is production | `false` mounts nothing: the middlewares only call `next()`. `true` mounts the hub in production too, with a warning. See [Production](#production). |
| `auth` | on | `false` turns off the one-time code. `{tokens: [...]}` keeps it on and trusts clients that send one of the [pairing tokens](../security.md#pairing-tokens). |
| `allowedOrigins` | loopback origins and the Chrome extension | Extra origins allowed to reach the hub, such as a tunnel. `false` turns the origin check and the request gate off. |
| `allowLan` | `false` | Answer other machines, such as a phone on Wi-Fi. Needs the one-time code on. |
| `terminals` | `false` | Add a dock that runs the project's build and test commands. See [Terminals](./terminals.md). |
| `mcp` | a bearer token | Mounts the MCP endpoint at `__mcp` and asks for a bearer token. With `auth: false` the default is `'auto'`: it mounts once agent tools exist and asks for no token. See [Send a token](../agents/mcp-server.md#send-a-token). |
The hub also takes the devtools options, such as `inspectors`, `agent`, `actions`, `redaction` and `limits`. See [Configuration](./configuration.md). Pass `browserDistFolder`, the folder that holds `index.csr.html`, to let the **Force Client render** override serve it. See [SSR overrides](../inspectors/ssr-http.md#ssr-overrides).
### Access control
The hub answers only requests from this machine, sent to a loopback `Host` such as `localhost:4000`, the same gate as the [Vite plugin](./vite.md#answers-only-your-machine). Other requests to the hub get `403`. Pass `allowLan: true` to also answer other machines, such as a [Capacitor](../guides/capacitor.md) app on Wi-Fi.
The hub protects its connection with a one-time code by default. The server prints the code, and a browser can read data only after it exchanges that code. On a machine only you use, pass `auth: false` to turn the code off.
The origin check is on by default too. Only loopback origins and the [Chrome extension](./chrome-extension.md#server-origin), `chrome-extension://dcogniffeelebaolkkfbopmjcblhblfk`, can open the WebSocket. A list in `allowedOrigins` keeps both and adds its entries. A custom origin registry passed as `allowedOrigins` still accepts the published extension. `allowedOrigins: false` turns the check off and prints a warning once. A build of the extension with another ID needs its own entry, with the ID from `chrome://extensions`:
```ts
// src/server.ts
import {initPangularHub} from '@pangular-inspector/devtools/hub';
const devtools = initPangularHub({
allowedOrigins: ['https://tunnel.example', 'chrome-extension://'],
});
```
[Access and redaction](../security.md) covers both checks.
The demo app in this repository mounts the hub like this:
```ts
// src/server.ts
const auth = process.env['PANGULAR_AUTH'] !== 'false';
const devtools = initPangularHub({
enabled:
(typeof ngDevMode === 'undefined' || !!ngDevMode) && process.env['NODE_ENV'] !== 'production',
ws: {sidecar: true},
auth,
});
if (devtools.enabled) {
app.use(devtools.nodeMiddleware);
app.use(devtools.ssrMiddleware);
}
```
It keeps the one-time code on unless `PANGULAR_AUTH` is `false`, and keeps the default origin check. The `enabled` check turns the hub off in a production build.
### Production
The hub is off in production: when `NODE_ENV` is `production`, or when the server is a production Angular build, where `ngDevMode` is `false`. `initPangularHub()` then mounts nothing: `nodeMiddleware` and `ssrMiddleware` only call `next()`, and `devtools.enabled` is `false`. Check `enabled` to skip the `app.use()` calls, as the demo does.
Pass `enabled: true` to mount the hub in production anyway, for example on a staging server only you can reach. The hub prints a warning when it starts. Pass `enabled: false` to keep it off in any environment.
The switch reads NODE_ENV and ngDevMode when initPangularHub() runs. A server that is not an Angular build, or that loads the package without bundling it, and does not set NODE_ENV=production, keeps the hub on. Pass enabled yourself, as the demo does.
## Load the overlay
### Import it in development
The [overlay](./overlay.md) collects live data from the page. Import it after bootstrap, in development only:
```ts {8-10}
// 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));
```
`ngDevMode` is false in production builds, so the import never runs there and the overlay stays out of your production bundle.
### The dock entries
A floating button appears on your page. It opens the devtools with one dock entry per tool:
| Dock entry | Shows |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Angular | Dashboard, components, routes, signals, injectors, forms, pipes, and SSR & HTTP |
| NgRx | Store patterns from source, and live state and actions |
| Analog | File routes, server calls, render modes and lint (a notice in non-Analog apps) |
| Angular Native | Components, signals, injectors, stores, queries, pipes and errors of a connected [Angular Native](./angular-native.md) app |
| NativeScript | Setup steps for [NativeScript apps](../guides/nativescript.md) |
| Capacitor | Plugin calls of a connected [Capacitor app](../inspectors/capacitor.md), or setup steps when none is connected |
[Popup and hub](./popup-and-hub.md) covers the panel, its dock modes and deep links.
## Run the app
### With the dev server
When you run `ng serve`, the Angular dev server runs `server.ts` too, so the hub answers on port 4200 as well.
```bash group="run" name="ng serve" image="https://cdn.simpleicons.org/angular/DD0031" active
ng serve
# open http://localhost:4200 and click the Pangular Inspector button
```
```bash group="run" name="SSR server" image="https://cdn.simpleicons.org/nodedotjs/5FA04E"
ng build --configuration development
NG_ALLOWED_HOSTS=localhost node dist//server/server.mjs
# open http://localhost:4000 and click the Pangular Inspector button
```
### With the built SSR server
To test the real Express process, build with the development configuration and start `server.mjs`. Replace `` with your project name.
From Angular 22.2, the built server answers only the hosts in its allowed list, which a new app leaves empty, so every page returns an error. Name the host in the `NG_ALLOWED_HOSTS` environment variable, as above, or in `security.allowedHosts` under the build options in `angular.json` (`projects..architect.build.options`):
```json
"security": {
"allowedHosts": ["localhost"]
}
```
ng build uses the production configuration by default. ngDevMode is false there, so the overlay is never imported and the button never appears. The live tabs need --configuration development. In this repository, the same applies to pnpm build.
## Fill the SSR & HTTP tab
### Add the providers
To fill the SSR & HTTP tab, add the interceptor and hydration hooks to your app config:
```ts {5,10-11}
// src/app/app.config.ts
import {provideHttpClient, withFetch} from '@angular/common/http';
import {ApplicationConfig} from '@angular/core';
import {provideClientHydration} from '@angular/platform-browser';
import {providePangularHttp, withPangular} from '@pangular-inspector/devtools/http';
export const appConfig: ApplicationConfig = {
providers: [
provideClientHydration(),
provideHttpClient(withFetch(), withPangular()),
providePangularHttp(),
],
};
```
`withPangular()` records requests and applies fault rules. `providePangularHttp()` captures hydration warnings before the overlay loads. In production builds the interceptor passes requests through untouched.
### Put `withPangular` first
Register `withPangular()` before your own interceptors, for example `provideHttpClient(withPangular(), withInterceptors([authInterceptor]))`. It then records requests as the app makes them, and fault rules apply before anything else.
### Trace each server render
To fill the **SSR requests** table, add the hub's `ssrMiddleware` after the hub middleware and before the Angular handler:
```ts {4}
// src/server.ts
const devtools = initPangularHub({ws: false});
app.use(devtools.nodeMiddleware);
app.use(devtools.ssrMiddleware);
```
It is optional. It also adds a `Server-Timing` header to each traced response. If the server uses `compression()`, mount `ssrMiddleware` after it. See [SSR & HTTP](../inspectors/ssr-http.md).
### Run SSR in the same process
SSR and the devtools middleware must run in the same Express process. Otherwise the server-side calls never reach the tab.
The [SSR & HTTP guide](../guides/ssr-http.md) covers interceptor order and fault injection in detail.
## Mount only the panel
To mount only the devtools panel without the dock, use `initDevframe()`. The devframe entry point re-exports it from the Devframe copy the package depends on:
```ts
// src/server.ts
import pangular, {initDevframe} from '@pangular-inspector/devtools/devframe';
const devtools = initDevframe(pangular, {base: '/__pangular/', ws: false});
app.use(devtools.nodeMiddleware);
```
`ws: false` makes the page and the panel connect over server-sent events on the same Express app. Without it, Devframe advertises a WebSocket that `nodeMiddleware` alone does not serve, and the page never connects. To serve a WebSocket instead, pass the HTTP server as `server`. See the `ws` and `server` options of `initDevframe`.
The overlay looks for `/__pangular/` too. Without the hub, every tab sits in one tab bar.
Like `@pangular-inspector/devtools/hub`, the devframe entry point loads Devframe from `node_modules` when it is imported, instead of being bundled into your server. That keeps the Angular 20 server build working: Angular 20 adds a top-level `createRequire` import to every server chunk, which collides with the same import in Devframe's own files. Install the package as a dependency of the app that runs the server.
## Troubleshooting
The app is probably a production build. Run ng serve, or build with --configuration development. Then check that main.ts imports the overlay.
The page could not reach the hub. Check that the hub middleware is mounted before express.static and the SSR handler, and that base matches the path the overlay uses. See No devtools server found.
Check that the server is running and that the hub middleware is mounted before express.static and the SSR handler. The panel keeps trying to connect; click Retry now to try at once.
The request did not come from this machine, was sent to a host other than a loopback host, or came from an origin the hub does not trust. The terminal names a refused origin or host. Open the app on localhost, add the origin to allowedOrigins, or pass allowLan: true for another device.
With auth on, a browser reads data only after it exchanges the one-time code the server printed. On a machine only you use, pass auth: false.
Add withPangular() and providePangularHttp(), and run SSR in the same Express process as the hub. Prerendered routes make no requests at runtime.
## Where to next
What the overlay sends, and how to point it at a custom mount path.
Dock modes, the hub rail, deep links and connection status.
Interceptor order, fault rules and hydration warnings.
Who can reach the hub, and what is redacted.