You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4266251
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: apps/docs/src/content/getting-started/cli.md
+21Lines changed: 21 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -126,11 +126,32 @@ When the server listens on your network (`--host 0.0.0.0` or a network address),
126
126
|`--allowed-origin <origin>`| An extra origin allowed to reach the server, such as `http://192.168.1.20:8100`. Repeat it for more. |
127
127
|`--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). |
128
128
|`--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). |
129
130
130
131
<ngmd-callouttype="warning"title="Keep it on localhost">
131
132
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 <ahref="../security.md">Access and redaction</a>.
132
133
</ngmd-callout>
133
134
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
+
134
155
### What it shows
135
156
136
157
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:
Copy file name to clipboardExpand all lines: apps/docs/src/content/getting-started/configuration.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -289,6 +289,16 @@ The server plugins themselves go in `serverPlugins`, an option of the Express hu
289
289
290
290
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.
291
291
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.
|`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).
| 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.
`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).
93
95
94
96
`initNativeScriptOverlay()` returns a function that stops the overlay and tells the server to forget every report the app sent.
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
+
42
44
## Mount the hub
43
45
44
46
Open `src/server.ts`. Import `initPangularHub` and mount its middleware right after `const app = express()`, before the generated `express.static` and Angular handlers:
Copy file name to clipboardExpand all lines: apps/docs/src/content/getting-started/vite.md
+39-1Lines changed: 39 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -100,6 +100,7 @@ pangular({
100
100
|`allowedOrigins`| none | Extra exact origins allowed to reach the devtools, for example a tunnel. |
101
101
|`auth`| on | Whether the devtools ask for the one-time code, and its pairing tokens. |
102
102
|`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. |
103
104
|`overlay`|`true`| Add the overlay to the pages the dev server serves. |
104
105
|`terminals`|`false`| Add a dock that runs the build and test commands. See [Terminals](./terminals.md). |
105
106
@@ -210,6 +211,43 @@ Start Vite on every interface too, with `server.host: true`. A request from anot
210
211
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.
211
212
</ngmd-alert>
212
213
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.
|`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
+
213
251
## Angular CLI apps
214
252
215
253
<ngmd-alertseverity="important">
@@ -220,7 +258,7 @@ Start Vite on every interface too, with `server.host: true`. A request from anot
220
258
221
259
<ngmd-accordion>
222
260
<ngmd-accordion-itemtitle="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.
224
262
</ngmd-accordion-item>
225
263
<ngmd-accordion-itemtitle="Why do I get a 403 from the devtools?">
226
264
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