Skip to content

Commit 419b430

Browse files
committed
docs: document ng add, LAN address injection and device network settings
Add ng add to the installation and quick start pages, lanAddress and --lan-address to the Vite, CLI, configuration and security pages, and the injected LAN address to the Capacitor and NativeScript guides. The native guides also show the Android network security config and the iOS App Transport Security and local network settings a device needs to reach the devtools over the LAN. Refs #373
1 parent 3c513ba commit 419b430

10 files changed

Lines changed: 235 additions & 16 deletions

File tree

‎apps/docs/src/content/getting-started/cli.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,11 +126,32 @@ When the server listens on your network (`--host 0.0.0.0` or a network address),
126126
| `--allowed-origin <origin>` | An extra origin allowed to reach the server, such as `http://192.168.1.20:8100`. Repeat it for more. |
127127
| `--proxy-origin <origin>` | The origin of your app's dev server when it proxies `/__pangular/` to this server, such as `http://localhost:4200`. The panel URL on that origin and the one-time code link point there, and the server accepts requests from that origin. See [Client-only Angular CLI app](./installation.md#client-only-angular-cli-app). |
128128
| `--auth-token <token>` | A [pairing token](../security.md#pairing-tokens) a client may send instead of the one-time code. Repeat it for more. Prefer the `PANGULAR_AUTH_TOKEN` environment variable. |
129+
| `--lan-address [address]` | Print the server's URL on your network and the define that injects it into a development build of a phone app. Off by default. Without a value it picks this machine's first private IPv4 address. Needs `--host` on the network. See [Inject the LAN address](#inject-the-lan-address). |
129130

130131
<ngmd-callout type="warning" title="Keep it on localhost">
131132
The server binds to <code>localhost</code> by default and asks for a one-time code. Changing <code>--host</code> or passing <code>--no-auth</code> widens who can reach it. See <a href="../security.md">Access and redaction</a>.
132133
</ngmd-callout>
133134

135+
### Inject the LAN address
136+
137+
A phone app (Capacitor, NativeScript) needs the server's address on your network. The CLI doesn't build your app, so `--lan-address` prints the URL and the define to pass to your app's build. Start the server on the network with it:
138+
139+
```bash
140+
npx pangular dev --host 0.0.0.0 --lan-address
141+
```
142+
143+
It prints lines like these after the startup lines:
144+
145+
```text
146+
LAN address for a device build: http://192.168.1.20:9999/
147+
Inject it as __PANGULAR_LAN_URL__, for example in an Angular CLI app:
148+
ng build --configuration development --define "__PANGULAR_LAN_URL__='http://192.168.1.20:9999/'"
149+
```
150+
151+
The `--define` flag needs the `application` builder of Angular 17.2 or later. The NativeScript overlay connects to the injected URL when you pass no `baseURL`, and `lanDevtoolsURL()` from `@pangular-inspector/devtools/overlay-manual` reads it in a Capacitor app. See [Set up Capacitor](../guides/capacitor.md#use-the-injected-lan-address) and [Set up NativeScript](../guides/nativescript.md#use-the-injected-lan-address).
152+
153+
`--lan-address` only prints. It doesn't change the host the server binds to, the origin check or the one-time code. With `--host localhost`, the default, it prints a warning and no address, since a phone can't reach that server. `--lan-address 192.168.1.20` names the address, for a machine on several networks. A loopback address is refused.
154+
134155
### What it shows
135156

136157
When no app is connected, the tabs show what your source declares. An [Angular Native](./angular-native.md) app connects through the **Angular Native apps** URL above and shows live data there:

‎apps/docs/src/content/getting-started/configuration.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,6 +265,16 @@ The server plugins themselves go in `serverPlugins`, an option of the Express hu
265265

266266
It is off by default because it starts processes on your machine. A value other than `true` or `false` prints a warning and keeps it off.
267267

268+
### LAN address
269+
270+
`lanAddress` is an option of the Vite plugin only, and `--lan-address` the matching flag of `pangular dev`. Like `terminals`, it is not part of `PangularConfig`, so `createPangular()` and the CLI config file don't take it.
271+
272+
| Option | Default | What it does |
273+
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
274+
| `lanAddress` | `false` | `true` injects the dev server's devtools URL on this machine's first private IPv4 address as `__PANGULAR_LAN_URL__`. An address such as `'192.168.1.20'` uses that one. Needs `allowLan` in effect. See [Inject the LAN address](./vite.md#inject-the-lan-address). |
275+
276+
A loopback address, `0.0.0.0` or any other value prints a warning and keeps it off. The CLI flag only prints the URL and the define for your build. See [Inject the LAN address](./cli.md#inject-the-lan-address).
277+
268278
### Lint rules
269279

270280
| Option | Default | What it does |

‎apps/docs/src/content/getting-started/installation.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,27 @@ bun add -D @pangular-inspector/devtools
122122

123123
MCP agent support (`@devframes/agentic`) and Devframe itself are included. You don't install them separately.
124124

125+
### Set up with ng add
126+
127+
In an Angular CLI workspace, `ng add` installs the package and wires it in for you:
128+
129+
```bash
130+
ng add @pangular-inspector/devtools
131+
```
132+
133+
It looks at the project and picks the setup this page describes for it:
134+
135+
| The project has | What `ng add` does |
136+
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
137+
| A `vite.config.ts` (Analog) | Adds `pangular()` to the `plugins` of the [Vite plugin](./vite.md). The plugin loads the overlay, so `main.ts` stays as it is. |
138+
| An Express `server.ts` (Angular SSR) | Adds `initPangularHub({ws: false})` and `app.use(devtools.nodeMiddleware)` right after `const app = express()`, as in [Angular CLI and Express](./express.md). Loads the overlay in `main.ts`. |
139+
| Neither | Loads the overlay in `main.ts`, and prints the steps to run the standalone CLI behind the `ng serve` proxy, as in [Client-only Angular CLI app](#client-only-angular-cli-app). |
140+
| A `server.ts` on another server, such as Hono | Loads the overlay in `main.ts`, leaves `server.ts` alone and points at [Hono, h3 and Fastify](./other-servers.md). |
141+
142+
The overlay goes after bootstrap, behind the `ngDevMode` check shown in [Browser part](#browser-part). Pass `--project <name>` in a workspace with several applications. Without it, `ng add` takes the only application, or the first one.
143+
144+
`ng add` only inserts lines next to code it recognizes, such as `import express from 'express'` and `const app = express()`. When a file looks different, it leaves the file alone and prints the snippet to add by hand. Running it again changes nothing: it skips files that already import the devtools. It saves the package as a dependency, which every setup works with. See [Dependency or dev dependency](#dependency-or-dev-dependency) to move it.
145+
125146
### Dependency or dev dependency
126147

127148
| Setup | Install it as |

‎apps/docs/src/content/getting-started/nativescript.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -76,11 +76,11 @@ The overlay marks its component reports with `platform: 'nativescript'`, the URL
7676

7777
`initNativeScriptOverlay()` takes an optional object:
7878

79-
| Option | Default | What it does |
80-
| ------------ | ------------------------------- | ----------------------------------------------------------------------------- |
81-
| `baseURL` | `defaultDevtoolsBaseURL()` | Absolute URL of the devtools server. |
82-
| `intervalMs` | The server's `limits.refreshMs` | How often the app reports, in milliseconds. |
83-
| `retryMs` | `5000` | How long to wait before connecting again after a failure or a dropped socket. |
79+
| Option | Default | What it does |
80+
| ------------ | --------------------------------------------------- | ----------------------------------------------------------------------------- |
81+
| `baseURL` | `lanDevtoolsURL()`, then `defaultDevtoolsBaseURL()` | Absolute URL of the devtools server. |
82+
| `intervalMs` | The server's `limits.refreshMs` | How often the app reports, in milliseconds. |
83+
| `retryMs` | `5000` | How long to wait before connecting again after a failure or a dropped socket. |
8484

8585
`defaultDevtoolsBaseURL(port = 9999)` is exported from the same entry point and picks the address by platform:
8686

@@ -89,7 +89,9 @@ The overlay marks its component reports with `platform: 'nativescript'`, the URL
8989
| iOS | `http://localhost:9999/` |
9090
| Android | `http://10.0.2.2:9999/` |
9191

92-
`10.0.2.2` is how the Android emulator reaches its host. The devtools server answers requests sent to it (and to `10.0.3.2`, Genymotion's address for the host) from the emulator without any option, as it does `localhost`. A physical device needs your machine's LAN address as `baseURL`.
92+
`10.0.2.2` is how the Android emulator reaches its host. The devtools server answers requests sent to it (and to `10.0.3.2`, Genymotion's address for the host) from the emulator without any option, as it does `localhost`. A physical device needs your machine's LAN address, as `baseURL` or injected by the build.
93+
94+
`lanDevtoolsURL()`, exported from the same entry point, returns the URL a development build defined as `__PANGULAR_LAN_URL__`, or `undefined`. When it returns one, the overlay connects there instead of to `defaultDevtoolsBaseURL()`. See [Use the injected LAN address](../guides/nativescript.md#use-the-injected-lan-address) and [Allow plain HTTP to your machine](../guides/nativescript.md#allow-plain-http-to-your-machine).
9395

9496
`initNativeScriptOverlay()` returns a function that stops the overlay and tells the server to forget every report the app sent.
9597

‎apps/docs/src/content/getting-started/quick-start.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ yarn add @pangular-inspector/devtools
3939
bun add @pangular-inspector/devtools
4040
```
4141

42+
To install the package and make the edits of the next two steps in one command, run `ng add @pangular-inspector/devtools`. See [Set up with ng add](./installation.md#set-up-with-ng-add). Then skip to [Open the panel](#open-the-panel).
43+
4244
## Mount the hub
4345

4446
Open `src/server.ts`. Import `initPangularHub` and mount its middleware right after `const app = express()`, before the generated `express.static` and Angular handlers:

‎apps/docs/src/content/getting-started/vite.md‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ pangular({
100100
| `allowedOrigins` | none | Extra exact origins allowed to reach the devtools, for example a tunnel. |
101101
| `auth` | on | Whether the devtools ask for the one-time code, and its pairing tokens. |
102102
| `allowLan` | `false` | Answer other machines, such as a phone on Wi-Fi, from listed origins. |
103+
| `lanAddress` | `false` | Inject the dev server's LAN address into the app, for a phone app. |
103104
| `overlay` | `true` | Add the overlay to the pages the dev server serves. |
104105
| `terminals` | `false` | Add a dock that runs the build and test commands. See [Terminals](./terminals.md). |
105106

@@ -210,6 +211,43 @@ Start Vite on every interface too, with `server.host: true`. A request from anot
210211
With <code>allowLan</code>, any device on the network can send requests that claim a listed origin. Only the one-time code, or a pairing token, keeps it from reading your app's data. Use it on a trusted network, and turn it off when you're done.
211212
</ngmd-alert>
212213

214+
### Inject the LAN address
215+
216+
A phone app built from the same Vite config, such as a bundled [Capacitor](../guides/capacitor.md#use-the-injected-lan-address) build, has no `localhost` to find the devtools on. `lanAddress` injects the dev server's devtools URL on your network into the app as the global constant `__PANGULAR_LAN_URL__`, for example `http://192.168.1.20:5173/__devframes/pangular/`. `lanDevtoolsURL()` from `@pangular-inspector/devtools/overlay-manual` reads it.
217+
218+
```ts
219+
// vite.config.ts
220+
import analog from '@analogjs/platform';
221+
import pangular from '@pangular-inspector/devtools/vite';
222+
import {defineConfig} from 'vite';
223+
224+
export default defineConfig({
225+
server: {host: true, port: 5173, strictPort: true},
226+
plugins: [
227+
analog(),
228+
pangular({
229+
allowLan: true,
230+
allowedOrigins: ['capacitor://localhost'],
231+
lanAddress: true,
232+
}),
233+
],
234+
});
235+
```
236+
237+
| `lanAddress` | What it injects |
238+
| ---------------- | ----------------------------------------------------------------------------------------------- |
239+
| `false` or unset | Nothing. The default. |
240+
| `true` | The first private IPv4 address of this machine (`10.x`, `172.16.x` to `172.31.x`, `192.168.x`). |
241+
| `'192.168.1.20'` | That address. Use it when the machine has several networks. |
242+
243+
The plugin injects an address only where the devtools already answer it, and changes nothing about who may connect:
244+
245+
- `allowLan` must be in effect: `allowLan: true`, the one-time code on, and a network origin in `allowedOrigins`. Otherwise the plugin prints `Not injecting the LAN address` with the reason.
246+
- `server.host` must put the dev server on the network, such as `true`. Set it in the config file, since a `vite build` doesn't see the `--host` flag of the dev server you run next to it.
247+
- The URL carries `server.port`, or `5173`. If Vite moves to another port because that one is taken, the plugin warns. `server.strictPort: true` makes Vite stop instead.
248+
249+
The constant reaches the pages the dev server serves and development builds, such as `vite build --mode development`. A production build, the default mode of `vite build`, gets nothing. The dev server also prints the URL as **Pangular Inspector (LAN)**.
250+
213251
## Angular CLI apps
214252

215253
<ngmd-alert severity="important">
@@ -220,7 +258,7 @@ Start Vite on every interface too, with `server.host: true`. A request from anot
220258

221259
<ngmd-accordion>
222260
<ngmd-accordion-item title="Does the plugin change my production build?" open>
223-
No. It applies to the dev server only, so the overlay script it adds is not part of a build.
261+
No. It applies to the dev server only, so the overlay script it adds is not part of a build. With <a href="#inject-the-lan-address"><code>lanAddress</code></a>, a build in a mode other than <code>production</code> also gets the <code>__PANGULAR_LAN_URL__</code> constant, and nothing else.
224262
</ngmd-accordion-item>
225263
<ngmd-accordion-item title="Why do I get a 403 from the devtools?">
226264
The request did not come from your machine, or its origin or the host it was sent to is not trusted. The terminal names a refused origin or host. Open the app on <code>localhost</code>, list your hostname in <code>server.allowedHosts</code>, or add the origin to <code>allowedOrigins</code>.

0 commit comments

Comments
 (0)