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 c08456e
Browse filesBrowse the repository at this point in the historyBrowse files
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.
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).
191
213
192
214
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.
Copy file name to clipboardExpand all lines: apps/docs/src/content/guides/angular-native.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -129,11 +129,13 @@ When it is ready, the server prints the Angular Native view on its own line:
129
129
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:
130
130
131
131
```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
133
133
```
134
134
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.
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.
137
139
</ngmd-alert>
138
140
139
141
See [Standalone CLI](../getting-started/cli.md) for the other server options and [Security](../security.md) for what `--no-auth` turns off.
| 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`|
26
26
| Vite plugin (Analog) |[Live reload on localhost](#live-reload-on-localhost)|[Live reload over Wi-Fi](#live-reload-over-wi-fi), with `allowLan`|
27
27
| 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`|
28
28
| Standalone CLI on its own |[A bundled build](#a-bundled-build)|[A bundled build](#a-bundled-build)|
29
29
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).
31
31
32
32
## Live reload on localhost
33
33
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.
35
35
36
36
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.
37
37
@@ -43,7 +43,7 @@ The page is then on `http://localhost:<port>`, the same origin as the devtools i
43
43
For example <code>ng serve --port 4200</code>.
44
44
</ngmd-step>
45
45
<ngmd-steptitle="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>.
47
47
</ngmd-step>
48
48
<ngmd-steptitle="Run the app">
49
49
<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
64
64
65
65
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`.
66
66
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
+
67
73
<ngmd-alertseverity="warning"label="Keep the one-time code on">
68
74
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.
69
75
</ngmd-alert>
@@ -72,9 +78,11 @@ Then start the dev server on every interface, for example `ng serve --host 0.0.0
72
78
73
79
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.
74
80
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).
@@ -114,38 +122,39 @@ Without `connectionMeta`, the overlay first fetches `__connection.json` from `ba
114
122
- 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`.
115
123
- 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`.
116
124
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.
| Android emulator or USB |`localhost`, after `adb reverse tcp:9999 tcp:9999` with your server's port |
123
131
| 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 |
124
133
125
134
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.
126
135
127
136
### Let the app reach your machine
128
137
129
138
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:
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`.
149
158
150
159
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`:
151
160
@@ -203,7 +212,7 @@ These keys are the same in Capacitor 6, 7 and 8. Keep the development ones out o
203
212
204
213
<ngmd-accordion>
205
214
<ngmd-accordion-itemtitle="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>.
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.
Copy file name to clipboardExpand all lines: apps/docs/src/content/guides/nativescript.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -114,11 +114,13 @@ The server listens on `localhost` only, which the iOS simulator and the Android
114
114
A physical device reaches your machine over the network, so the server has to listen on an interface the device can reach:
115
115
116
116
```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
118
118
```
119
119
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.
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.
122
124
</ngmd-alert>
123
125
124
126
See [Standalone CLI](../getting-started/cli.md) for the other server options and [Security](../security.md) for what `--no-auth` turns off.
Copy file name to clipboardExpand all lines: apps/docs/src/content/inspectors/capacitor.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,7 +67,7 @@ The log starts when the overlay starts, unless the app loads the Capacitor hook
67
67
68
68
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.
69
69
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:
71
71
72
72
```json
73
73
// angular.json (excerpt)
@@ -88,7 +88,7 @@ Add the hook to the polyfills of your development configuration, so it loads bef
88
88
}
89
89
```
90
90
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.
92
92
93
93
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.
94
94
@@ -132,7 +132,7 @@ To turn the inspector off, set `inspectors.capacitor` to `false`. The tab, the d
132
132
On the web, plugins don't use the native bridge. Load the Capacitor hook before <code>@capacitor/core</code> to log the calls their web implementations answer. See <a href="#web-calls">Web calls</a>.
133
133
</ngmd-accordion-item>
134
134
<ngmd-accordion-itemtitle="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.
136
136
</ngmd-accordion-item>
137
137
<ngmd-accordion-itemtitle="Why are my startup calls missing?">
138
138
They ran before the overlay started. Load the Capacitor hook from your polyfills. See <a href="#startup-calls">Startup calls</a>.
0 commit comments