Skip to content

Commit c08456e

Browse files
committed
docs(overlay): fill the gaps a first Capacitor setup runs into
The Capacitor guide covers Angular's allowed hosts under SSR, installing the package for a bundled build, iOS devices on the network, --forwardPorts, a narrower config sample and blocked requests in troubleshooting. The token sample builds in every clone, the polyfills sample says to copy the base list, and the native guides open the panel where the server listens.
1 parent d9bddd0 commit c08456e

6 files changed

Lines changed: 58 additions & 23 deletions

File tree

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

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -172,9 +172,29 @@ The endpoints must still accept the page's origin. [Set up Capacitor](../guides/
172172

173173
If the server has [pairing tokens](../security.md#pairing-tokens), pass one as `authToken` and the page is trusted without the code:
174174

175+
Commit a stub that holds no token, so every clone builds:
176+
177+
```ts
178+
// src/devtools-token.ts (committed)
179+
export const devtoolsToken: string | undefined = undefined;
180+
```
181+
182+
Keep the real token in a second file that git ignores, and swap it in with a build configuration of your own:
183+
175184
```ts
176-
// src/devtools-token.ts (listed in .gitignore)
177-
export const devtoolsToken = 'the value of PANGULAR_AUTH_TOKEN on your machine';
185+
// src/devtools-token.local.ts (listed in .gitignore)
186+
export const devtoolsToken: string | undefined = 'the value of PANGULAR_AUTH_TOKEN on your machine';
187+
```
188+
189+
```json
190+
// angular.json (excerpt, under projects.my-app.architect.build.configurations)
191+
{
192+
"device": {
193+
"fileReplacements": [
194+
{"replace": "src/devtools-token.ts", "with": "src/devtools-token.local.ts"}
195+
]
196+
}
197+
}
178198
```
179199

180200
```ts
@@ -187,7 +207,9 @@ await initOverlay({
187207
});
188208
```
189209

190-
The token is a development secret. Keep the file out of git. The page keeps the token in its `localStorage`, and sends it in the query string of its connection URL. See [Pairing tokens](../security.md#pairing-tokens).
210+
Build with `ng build --configuration development,device`. Without the `device` configuration, as in a clone that has no local file, the stub leaves `authToken` out and the page asks for the code.
211+
212+
The token is a development secret. Keep the local file out of git. The page keeps the token in its `localStorage`, and sends it in the query string of its connection URL. See [Pairing tokens](../security.md#pairing-tokens).
191213

192214
When the server refuses the token, the overlay logs a warning in the console and asks for the code instead. With `connectionMeta`, it also logs a warning once when it can't reach the server.
193215

‎apps/docs/src/content/guides/angular-native.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -129,11 +129,13 @@ When it is ready, the server prints the Angular Native view on its own line:
129129
A physical device over Wi-Fi reaches your machine over the network, so the server has to listen on an interface the device can reach:
130130

131131
```bash
132-
npx @pangular-inspector/devtools dev --host 192.168.1.20 --no-auth
132+
npx @pangular-inspector/devtools dev --host 192.168.1.20 --allowed-origin http://192.168.1.20:9999 --no-auth
133133
```
134134

135+
The server then listens on that address only, not on `localhost`, so open the panel at `http://192.168.1.20:9999/`. `--allowed-origin` lets the panel's own origin through there. Use your machine's address and the server's port.
136+
135137
<ngmd-alert severity="warning" label="Trusted networks only">
136-
With <code>--host</code> and <code>--no-auth</code>, every host that can reach that address can call the devtools RPC and MCP endpoints without a code. Use it on a trusted network only, and bind to the one interface the device uses rather than <code>0.0.0.0</code>.
138+
With <code>--host</code> and <code>--no-auth</code>, every host that can reach that address can call the devtools RPC and MCP endpoints without a code. Use it on a trusted network only. Binding to the one address the device uses, as above, keeps the server off your other interfaces, which <code>0.0.0.0</code> would not.
137139
</ngmd-alert>
138140

139141
See [Standalone CLI](../getting-started/cli.md) for the other server options and [Security](../security.md) for what `--no-auth` turns off.

‎apps/docs/src/content/guides/capacitor.md‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,18 @@ This guide adds the devtools to an Ionic or Capacitor *Angular app. The app runs
2020

2121
## Which setup you need
2222

23-
| Your devtools server | iOS simulator, Android emulator, USB device | Phone over Wi-Fi |
23+
| Your devtools server | iOS simulator, Android emulator or USB device | Phone over Wi-Fi, and any iPhone or iPad |
2424
| -------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
2525
| Express hub in `server.ts` | [Live reload on localhost](#live-reload-on-localhost) | [Live reload over Wi-Fi](#live-reload-over-wi-fi), with `allowedOrigins` |
2626
| Vite plugin (Analog) | [Live reload on localhost](#live-reload-on-localhost) | [Live reload over Wi-Fi](#live-reload-over-wi-fi), with `allowLan` |
2727
| Standalone CLI behind `ng serve` | [Live reload on localhost](#live-reload-on-localhost) | [Live reload over Wi-Fi](#live-reload-over-wi-fi), with `--allowed-origin` |
2828
| Standalone CLI on its own | [A bundled build](#a-bundled-build) | [A bundled build](#a-bundled-build) |
2929

30-
Over Wi-Fi, the page's origin is your machine's network address, not `localhost`, so the server has to allow that origin. A bundled build works with any server that the phone can reach.
30+
USB applies to Android only: `adb reverse` forwards the port. An iPhone or iPad reaches your machine over the network, even when it is plugged in. Over Wi-Fi, the page's origin is your machine's network address, not `localhost`, so the server has to allow that origin. A bundled build works with the standalone CLI and the Express hub, and with the Vite plugin for iOS. See [Run the server where the device reaches it](#run-the-server-where-the-device-reaches-it).
3131

3232
## Live reload on localhost
3333

34-
`npx cap run <platform> --live-reload` points the WebView at your dev server by setting `server.url` for that run. It does not start the dev server. Start it yourself, then pass its port and `--host localhost`. Without `--host`, Capacitor uses your machine's network address, and the port defaults to 3000.
34+
These steps use the Capacitor CLI of Capacitor 6, 7 and 8. `npx cap run <platform> --live-reload` points the WebView at your dev server by setting `server.url` for that run. It does not start the dev server. Start it yourself, then pass its port and `--host localhost`. Without `--host`, Capacitor uses your machine's network address, and the port defaults to 3000.
3535

3636
The page is then on `http://localhost:<port>`, the same origin as the devtools in that server. Load the overlay the usual way, as in [Browser overlay](../getting-started/overlay.md), with `@pangular-inspector/devtools/overlay`. It finds the server next to the page and adds the floating button inside the app.
3737

@@ -43,7 +43,7 @@ The page is then on `http://localhost:<port>`, the same origin as the devtools i
4343
For example <code>ng serve --port 4200</code>.
4444
</ngmd-step>
4545
<ngmd-step title="Forward the port on Android">
46-
For the Android emulator or a USB device, run <code>adb reverse tcp:4200 tcp:4200</code>. The iOS simulator shares your machine's <code>localhost</code>.
46+
For the Android emulator or a USB device, run <code>adb reverse tcp:4200 tcp:4200</code>, or add <code>--forwardPorts 4200:4200</code> to the run command below, which runs it for you. The iOS simulator shares your machine's <code>localhost</code>.
4747
</ngmd-step>
4848
<ngmd-step title="Run the app">
4949
<code>npx cap run ios --live-reload --host localhost --port 4200</code>, or the same with <code>android</code>.
@@ -64,6 +64,12 @@ A phone on Wi-Fi loads the app from your machine's network address, such as `htt
6464

6565
Then start the dev server on every interface, for example `ng serve --host 0.0.0.0 --port 4200`, and run `npx cap run ios --live-reload --host 192.168.1.20 --port 4200`. The overlay loads as in a browser, through `@pangular-inspector/devtools/overlay`.
6666

67+
With SSR, Angular also checks the host of each request it renders, and refuses your network address with `URL with hostname "192.168.1.20" is not allowed`. Allow it in `security.allowedHosts`, in the build options of `angular.json`, or for one run with the `NG_ALLOWED_HOSTS` environment variable:
68+
69+
```bash
70+
NG_ALLOWED_HOSTS=192.168.1.20 ng serve --host 0.0.0.0 --port 4200
71+
```
72+
6773
<ngmd-alert severity="warning" label="Keep the one-time code on">
6874
On a network address, anyone on the network can reach the server, and the origin check alone does not stop a client that sends an allowed <code>Origin</code>. The one-time code keeps them out. Don't pass <code>auth: false</code> in this setup, and use a trusted network.
6975
</ngmd-alert>
@@ -72,9 +78,11 @@ Then start the dev server on every interface, for example `ng serve --host 0.0.0
7278

7379
A bundled build loads the app from `capacitor://localhost` on iOS and from `https://localhost` on Android. Start the overlay yourself with `@pangular-inspector/devtools/overlay-manual`, and pass the server's address and its connection info.
7480

81+
The overlay is bundled into the app here, so install the package in the app first, even when the server runs on its own. See [Installation](../getting-started/installation.md).
82+
7583
### Start the overlay
7684

77-
```ts {6-12}
85+
```ts {8-14}
7886
// src/main.ts
7987
import {bootstrapApplication} from '@angular/platform-browser';
8088
import {App} from './app/app';
@@ -114,38 +122,39 @@ Without `connectionMeta`, the overlay first fetches `__connection.json` from `ba
114122
- The hub's WebSocket side-car (`ws: {sidecar: true}`) listens on `localhost` on a port it picks, so a device can't reach it. Use `ws: false`.
115123
- With the Vite plugin, add `capacitor://localhost` to its `allowedOrigins` for iOS. Android's `https://localhost` needs no entry, but only reaches Vite through the emulator or `adb reverse`.
116124

117-
The short forms above carry no `configs`, so the overlay uses the default inspectors, limits and redaction, and logs a warning. The server's `redaction.secretNames` are then not applied on the page. If your server has a [config](../getting-started/configuration.md), open its `__connection.json` in your desktop browser, for example `http://localhost:9999/__connection.json`, and pass the whole object as `connectionMeta`.
125+
The short forms above carry no `configs`, so the overlay uses the default inspectors, limits and redaction, and logs a warning. The server's `redaction.secretNames` are then not applied on the page. The warning only says that the page runs with the defaults, so it can be ignored when the server has no config. If your server has a [config](../getting-started/configuration.md), open its `__connection.json` in your desktop browser and pass the whole object as `connectionMeta`: `http://localhost:9999/__connection.json` for the CLI, or `http://localhost:4000/__devframes/pangular/__connection.json` for the hub.
118126

119127
| Where the app runs | `<address>` |
120128
| ----------------------- | -------------------------------------------------------------------------- |
121129
| iOS simulator | `localhost` |
122130
| Android emulator or USB | `localhost`, after `adb reverse tcp:9999 tcp:9999` with your server's port |
123131
| Phone over Wi-Fi | Your machine's network address, such as `192.168.1.20` |
132+
| iPhone or iPad | Your machine's network address, over Wi-Fi or USB |
124133

125134
The standalone CLI and the Express hub accept `capacitor://localhost` and `https://localhost` without an `allowedOrigins` entry, because their host is `localhost`. The Vite plugin accepts `https://localhost` the same way, and `capacitor://localhost` once it is in `allowedOrigins`. That entry also turns the one-time code on.
126135

127136
### Let the app reach your machine
128137

129138
The page is `https://localhost` on Android and the server is plain HTTP, so the Android WebView blocks the connection as mixed content. Android also blocks cleartext traffic. Allow both in a development build:
130139

131-
```ts {4,10-11}
140+
```ts {4,8-9}
132141
// capacitor.config.ts
133142
import type {CapacitorConfig} from '@capacitor/cli';
134143

135144
const devtools = process.env['CAPACITOR_DEVTOOLS'] === '1';
136145

137146
const config: CapacitorConfig = {
138-
appId: 'com.example.trips',
139-
appName: 'Trips',
140-
webDir: 'www',
147+
// Your appId, appName, webDir and other keys, as they are.
141148
server: devtools ? {cleartext: true} : undefined,
142149
android: devtools ? {allowMixedContent: true} : undefined,
143150
};
144151

145152
export default config;
146153
```
147154

148-
Capacitor applies both on `npx cap sync`, which `npx cap run` also runs, so set the flag there: `CAPACITOR_DEVTOOLS=1 npx cap run android`. `server.cleartext` sets `android:usesCleartextTraffic` in the manifest of the `capacitor-cordova-android-plugins` module, which Android merges into the app. Setting `server.androidScheme` to `'http'` also avoids mixed content, but it changes the app's origin, so the WebView no longer sees the data the app stored under `https://localhost`.
155+
If your config already has a `server` or `android` block, add the keys to it instead.
156+
157+
With `adb reverse`, the server is at `http://localhost`, which Chromium may not count as mixed content. Keep both settings anyway: they cost nothing in a development build. Capacitor applies both on `npx cap sync`, which `npx cap run` also runs, so set the flag there: `CAPACITOR_DEVTOOLS=1 npx cap run android`. `server.cleartext` sets `android:usesCleartextTraffic` in the manifest of the `capacitor-cordova-android-plugins` module, which Android merges into the app. Setting `server.androidScheme` to `'http'` also avoids mixed content, but it changes the app's origin, so the WebView no longer sees the data the app stored under `https://localhost`.
149158

150159
On iOS, App Transport Security can block plain HTTP to a network address. If it does, allow local networking in a development build's `ios/App/App/Info.plist`:
151160

@@ -203,7 +212,7 @@ These keys are the same in Capacitor 6, 7 and 8. Keep the development ones out o
203212

204213
<ngmd-accordion>
205214
<ngmd-accordion-item title="The panel never shows the app" open>
206-
Inspect the WebView, with Safari's <strong>Develop</strong> menu for iOS or <code>chrome://inspect</code> for Android, and read the console. <code>[pangular] No devtools server found</code> in a bundled build means <code>connectionMeta</code> is missing. A <strong>Mixed Content</strong> message means <code>allowMixedContent</code> is off, and the overlay sends nothing. A failed connection to the address means the server is not running, listens only on <code>localhost</code>, or the address is wrong for where the app runs. A <code>403</code> under live reload over Wi-Fi means the page's origin is missing from <code>allowedOrigins</code>.
215+
Inspect the WebView, with Safari's <strong>Develop</strong> menu for iOS or <code>chrome://inspect</code> for Android, and read the console. <code>[pangular] No devtools server found</code> in a bundled build means <code>connectionMeta</code> is missing, or the WebView blocked the request. A <strong>Mixed Content</strong> message next to it means <code>allowMixedContent</code> is off, and a cleartext error means <code>server.cleartext</code> is. In both cases the overlay sends nothing. A failed connection to the address means the server is not running, listens only on <code>localhost</code>, or the address is wrong for where the app runs. A <code>403</code> under live reload over Wi-Fi means the page's origin is missing from <code>allowedOrigins</code>. A <code>400</code> page with <code>is not allowed</code> under SSR means the address is missing from Angular's <code>security.allowedHosts</code>, as in <a href="#live-reload-over-wi-fi">Live reload over Wi-Fi</a>.
207216
</ngmd-accordion-item>
208217
<ngmd-accordion-item title="The code dialog keeps coming back">
209218
The app's origin changed, its storage was cleared, or the code expired before you typed it. Under live reload over Wi-Fi, another network address is another origin. Type the newest code the server printed.

‎apps/docs/src/content/guides/nativescript.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,11 +114,13 @@ The server listens on `localhost` only, which the iOS simulator and the Android
114114
A physical device reaches your machine over the network, so the server has to listen on an interface the device can reach:
115115

116116
```bash
117-
npx @pangular-inspector/devtools dev --host 192.168.1.20 --no-auth
117+
npx @pangular-inspector/devtools dev --host 192.168.1.20 --allowed-origin http://192.168.1.20:9999 --no-auth
118118
```
119119

120+
The server then listens on that address only, not on `localhost`, so open the panel at `http://192.168.1.20:9999/`. `--allowed-origin` lets the panel's own origin through there. Use your machine's address and the server's port.
121+
120122
<ngmd-alert severity="warning" label="Trusted networks only">
121-
With <code>--host</code> and <code>--no-auth</code>, every host that can reach that address can call the devtools RPC and MCP endpoints without a code. Use it on a trusted network only, and bind to the one interface the device uses rather than <code>0.0.0.0</code>.
123+
With <code>--host</code> and <code>--no-auth</code>, every host that can reach that address can call the devtools RPC and MCP endpoints without a code. Use it on a trusted network only. Binding to the one address the device uses, as above, keeps the server off your other interfaces, which <code>0.0.0.0</code> would not.
122124
</ngmd-alert>
123125

124126
See [Standalone CLI](../getting-started/cli.md) for the other server options and [Security](../security.md) for what `--no-auth` turns off.

‎apps/docs/src/content/inspectors/capacitor.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The log starts when the overlay starts, unless the app loads the Capacitor hook
6767

6868
A call that a plugin's web implementation answers never reaches the native bridge, and neither does the **Not implemented** error that `@capacitor/core` raises for a method no platform implements. The tab sees these calls only when `@pangular-inspector/devtools/capacitor-hook` runs before `@capacitor/core`. On the web, without the hook, the tab says that calls aren't shown.
6969

70-
Add the hook to the polyfills of your development configuration, so it loads before your app and stays out of production builds:
70+
Add the hook to the polyfills of your development configuration, so it loads before your app and stays out of production builds. A configuration's `polyfills` replace the list in the build's `options`, so copy that list and add the hook to it:
7171

7272
```json
7373
// angular.json (excerpt)
@@ -88,7 +88,7 @@ Add the hook to the polyfills of your development configuration, so it loads bef
8888
}
8989
```
9090

91-
Leave `zone.js` out if your app doesn't use it. The hook starts on import, and does nothing when `ngDevMode` is off.
91+
This sample assumes the base list is `["zone.js"]`. Leave `zone.js` out if your app doesn't use it. The hook starts on import, and does nothing when `ngDevMode` is off.
9292

9393
If the hook runs after `@capacitor/core`, it logs native calls only and changes nothing else. In that case, the tab still records a **Not implemented** error that your app leaves unhandled.
9494

@@ -132,7 +132,7 @@ To turn the inspector off, set `inspectors.capacitor` to `false`. The tab, the d
132132
On the web, plugins don't use the native bridge. Load the Capacitor hook before <code>&#64;capacitor/core</code> to log the calls their web implementations answer. See <a href="#web-calls">Web calls</a>.
133133
</ngmd-accordion-item>
134134
<ngmd-accordion-item title="Does watching the calls change them?">
135-
No. The wrappers hand the app the same promise, arguments and results, and the hook passes everything through once it stops.
135+
No. The app gets a promise that settles the same way, with the same arguments and results, and a rejection the app leaves unhandled still reaches <code>unhandledrejection</code>. The hook passes everything through once it stops.
136136
</ngmd-accordion-item>
137137
<ngmd-accordion-item title="Why are my startup calls missing?">
138138
They ran before the overlay started. Load the Capacitor hook from your polyfills. See <a href="#startup-calls">Startup calls</a>.

0 commit comments

Comments
 (0)