Skip to content

Commit 4266251

Browse files
authored
feat: add an ng add schematic and opt-in LAN address injection (#484)
Adds an `ng add` schematic that detects the setup (Vite, Express or the overlay alone) and wires the files it recognizes, printing the snippet for anything else. Also adds an opt-in lanAddress option for the Vite plugin and CLI that injects the dev server's LAN devtools URL at build time, with docs for the native network settings. Refs #373
1 parent 5189ef5 commit 4266251

27 files changed

Lines changed: 1946 additions & 52 deletions

‎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
@@ -289,6 +289,16 @@ The server plugins themselves go in `serverPlugins`, an option of the Express hu
289289

290290
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.
291291

292+
### LAN address
293+
294+
`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.
295+
296+
| Option | Default | What it does |
297+
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298+
| `lanAddress` | `false` | `true` injects the dev server's devtools URL on this machine's first private IPv4 address, or its first network address when none is private, 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). |
299+
300+
`false` keeps it off with no warning. `true` and a network IPv4 address turn it on. Any other value, such as a loopback address, `0.0.0.0` or a value that is not a boolean or an IPv4 address, 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).
301+
292302
### Lint rules
293303

294304
| 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. It reads `angular.json` the way the Angular CLI does, with comments and trailing commas. When it can't read it, it changes nothing and prints the overlay snippet, and with `--project` it stops with an error that names `angular.json`. 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)