@metricinsights/pp-dev 1.5.0-beta.24 → 1.5.0-beta.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -151
- package/dist/cjs/cli.js +1 -1
- package/dist/cjs/cli.js.map +1 -1
- package/dist/cjs/package.json +2 -132
- package/dist/cjs/plugin.js +1 -1
- package/dist/cjs/{request-capture.middleware-Jk6Vxx40.js → request-capture.middleware-0msmv4A0.js} +2 -2
- package/dist/cjs/{request-capture.middleware-Jk6Vxx40.js.map → request-capture.middleware-0msmv4A0.js.map} +1 -1
- package/dist/esm/cli.js +1 -1
- package/dist/esm/cli.js.map +1 -1
- package/dist/esm/package.json +2 -132
- package/dist/esm/plugin.js +1 -1
- package/dist/esm/request-capture.middleware-Dt_17Nnw.js +2 -0
- package/dist/esm/request-capture.middleware-Dt_17Nnw.js.map +1 -0
- package/dist/types/helpers.d.ts +29 -0
- package/dist/types/index.d.ts +7 -190
- package/dist/types/plugin.d.ts +8 -0
- package/dist/types/pp-dev-config-D889A-PO.d.ts +189 -0
- package/package.json +5 -8
- package/dist/CHANGELOG.md +0 -442
- package/dist/README.md +0 -765
- package/dist/esm/request-capture.middleware-B9t-px8Z.js +0 -2
- package/dist/esm/request-capture.middleware-B9t-px8Z.js.map +0 -1
package/README.md
CHANGED
|
@@ -31,18 +31,18 @@ npm install @metricinsights/pp-dev
|
|
|
31
31
|
This package requires Next.js as a peer dependency for certain functionality:
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
|
-
npm install next@^
|
|
34
|
+
npm install next@^16
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
**Note**: pp-dev
|
|
37
|
+
**Note**: pp-dev accepts Next.js 13 to 16 (`peerDependencies`: `>= 13 < 17`); the test apps run on Next.js 16. It is a peer dependency, so it isn't installed with pp-dev.
|
|
38
38
|
|
|
39
39
|
## Package Structure
|
|
40
40
|
|
|
41
41
|
The pp-dev package provides multiple entry points for different use cases:
|
|
42
42
|
|
|
43
43
|
```javascript
|
|
44
|
-
// Main package (includes everything)
|
|
45
|
-
import
|
|
44
|
+
// Main package (includes everything, defineConfig too)
|
|
45
|
+
import { withPPDev } from '@metricinsights/pp-dev';
|
|
46
46
|
|
|
47
47
|
// Plugin only (for Vite integration)
|
|
48
48
|
import { vitePPDev } from '@metricinsights/pp-dev/plugin';
|
|
@@ -51,7 +51,7 @@ import { vitePPDev } from '@metricinsights/pp-dev/plugin';
|
|
|
51
51
|
import { defineConfig } from '@metricinsights/pp-dev/helpers';
|
|
52
52
|
|
|
53
53
|
// Client assets (for development UI)
|
|
54
|
-
import '@metricinsights/pp-dev/client/
|
|
54
|
+
import '@metricinsights/pp-dev/client/client.css';
|
|
55
55
|
```
|
|
56
56
|
|
|
57
57
|
## Configuration
|
|
@@ -144,62 +144,62 @@ module.exports = defineConfig({
|
|
|
144
144
|
|
|
145
145
|
### `mi` — Metric Insights connection
|
|
146
146
|
|
|
147
|
-
| Field | Type
|
|
148
|
-
|
|
149
|
-
| `url` | `string`
|
|
150
|
-
| `token` | `string`
|
|
151
|
-
| `mode` | `'standalone' \| 'embedding'`
|
|
152
|
-
| `include` | `'top-bar' \| 'shared-components'
|
|
153
|
-
| `apiVersion` | `6 \| 7`
|
|
147
|
+
| Field | Type | Default | Description |
|
|
148
|
+
| ------------ | ---------------------------------- | --------------------- | --------------------------------------------------------------- |
|
|
149
|
+
| `url` | `string` | — | URL of the Metric Insights instance |
|
|
150
|
+
| `token` | `string` | `MI_ACCESS_TOKEN` env | Personal access token for authentication |
|
|
151
|
+
| `mode` | `'standalone' \| 'embedding'` | `'standalone'` | Standalone hides the MI navigation; embedding keeps it |
|
|
152
|
+
| `include` | `'top-bar' \| 'shared-components'` | — | Bundle MI top-bar assets into the build (requires `standalone`) |
|
|
153
|
+
| `apiVersion` | `6 \| 7` | `7` | MI API version to target |
|
|
154
154
|
|
|
155
155
|
### `app` — Portal Page identity
|
|
156
156
|
|
|
157
|
-
| Field | Type
|
|
158
|
-
|
|
159
|
-
| `id` | `number`
|
|
160
|
-
| `type` | `'template' \| 'page'`
|
|
161
|
-
| `name` | `string`
|
|
157
|
+
| Field | Type | Default | Description |
|
|
158
|
+
| ------ | ---------------------- | ------------------- | -------------------------------------------------------- |
|
|
159
|
+
| `id` | `number` | — | Portal Page ID used to fetch template variables |
|
|
160
|
+
| `type` | `'template' \| 'page'` | `'template'` | `template` syncs back to MI; `page` is standalone-only |
|
|
161
|
+
| `name` | `string` | `package.json#name` | Template name on the MI instance (usually auto-resolved) |
|
|
162
162
|
|
|
163
163
|
### `proxy` — Request proxying
|
|
164
164
|
|
|
165
|
-
| Field
|
|
166
|
-
|
|
167
|
-
| `cache`
|
|
168
|
-
| `cacheTtl`
|
|
169
|
-
| `tls.allowSelfSigned` | `boolean` | `false`
|
|
165
|
+
| Field | Type | Default | Description |
|
|
166
|
+
| --------------------- | --------- | -------- | --------------------------------------------------- |
|
|
167
|
+
| `cache` | `boolean` | `true` | Enable caching of proxied requests |
|
|
168
|
+
| `cacheTtl` | `number` | `600000` | Cache TTL in milliseconds (10 minutes) |
|
|
169
|
+
| `tls.allowSelfSigned` | `boolean` | `false` | Allow self-signed SSL certificates on the MI server |
|
|
170
170
|
|
|
171
171
|
### `build` — Build output
|
|
172
172
|
|
|
173
|
-
| Field
|
|
174
|
-
|
|
175
|
-
| `outDir`
|
|
176
|
-
| `zip`
|
|
177
|
-
| `versionFile`
|
|
178
|
-
| `imageOptimisations
|
|
173
|
+
| Field | Type | Default | Description |
|
|
174
|
+
| -------------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| `outDir` | `string` | `'dist'` | Output directory |
|
|
176
|
+
| `zip` | `boolean \| { fileName?: string; outDir?: string; inDir?: string }` | `true` | Zip build output. Object form customizes filename and directories. |
|
|
177
|
+
| `versionFile` | `boolean \| { enabled?: boolean; fileNameTemplate?: string }` | `true` | Write a VERSION file into the build |
|
|
178
|
+
| `imageOptimisations` | `boolean \| Record<string, unknown>` | `true` | Image optimization. See [vite-plugin-image-optimizer](https://www.npmjs.com/package/vite-plugin-image-optimizer#plugin-options) for object options |
|
|
179
179
|
|
|
180
180
|
### `inspector` — Request Inspector
|
|
181
181
|
|
|
182
|
-
| Field | Type | Default | Description
|
|
183
|
-
|
|
184
|
-
| `enabled` | `boolean` | `true` | Enable the request inspector
|
|
185
|
-
| `maxMemory` | `number` | `104857600` | Max total body memory (bytes) before oldest entries are evicted (default 100 MB)
|
|
182
|
+
| Field | Type | Default | Description |
|
|
183
|
+
| -------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------- |
|
|
184
|
+
| `enabled` | `boolean` | `true` | Enable the request inspector |
|
|
185
|
+
| `maxMemory` | `number` | `104857600` | Max total body memory (bytes) before oldest entries are evicted (default 100 MB) |
|
|
186
186
|
| `captureLimit` | `number` | `10485760` | Max body size captured per request/response (bytes, default 10 MB). Larger bodies are stored truncated. |
|
|
187
187
|
|
|
188
188
|
### `sync` — Template sync
|
|
189
189
|
|
|
190
|
-
| Field
|
|
191
|
-
|
|
192
|
-
| `backupsDir`
|
|
193
|
-
| `maxBackups`
|
|
194
|
-
| `buildTimeoutMs` | `number`
|
|
190
|
+
| Field | Type | Default | Description |
|
|
191
|
+
| ---------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
192
|
+
| `backupsDir` | `string` | `'backups'` | Directory for backups from the MI server |
|
|
193
|
+
| `maxBackups` | `number \| false` | `20` | How many of this page's backups to keep; each new backup deletes the oldest beyond that. `false` or `0` keeps them all. |
|
|
194
|
+
| `buildTimeoutMs` | `number` | `600000` | How long the build a sync starts (`pp-dev build`, `next build`) may run, in milliseconds, before it is stopped and the sync fails (default 10 minutes). |
|
|
195
195
|
|
|
196
196
|
### `devPanel` — Dev panel appearance
|
|
197
197
|
|
|
198
|
-
| Field | Type
|
|
199
|
-
|
|
200
|
-
| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`
|
|
201
|
-
| `hidden` | `boolean`
|
|
202
|
-
| `autoHide` | `boolean`
|
|
198
|
+
| Field | Type | Default | Description |
|
|
199
|
+
| ---------- | -------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------- |
|
|
200
|
+
| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | Screen corner the dev panel is anchored to |
|
|
201
|
+
| `hidden` | `boolean` | `false` | Fully hide the panel. Restore in the browser with `?pp-dev-panel=show` |
|
|
202
|
+
| `autoHide` | `boolean` | `false` | Panel slides behind the screen edge leaving a thin strip; hover reveals it |
|
|
203
203
|
|
|
204
204
|
These values are **defaults**: the panel itself has a settings popover (gear icon) with a corner
|
|
205
205
|
picker, an auto-hide toggle and a hide button, and the panel can be dragged by its grip handle and
|
|
@@ -213,16 +213,16 @@ section for the full feature description.
|
|
|
213
213
|
|
|
214
214
|
### `users` — Working as other users
|
|
215
215
|
|
|
216
|
-
| Field | Type | Default | Description
|
|
217
|
-
|
|
216
|
+
| Field | Type | Default | Description |
|
|
217
|
+
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
218
218
|
| `persist` | `boolean` | `false` | Keep the users added with an API token between dev server runs, in `~/.pp-dev/users/` (plain text, readable by you only; on Windows, by your profile's permissions) |
|
|
219
219
|
|
|
220
220
|
See [Working as other users](#working-as-other-users).
|
|
221
221
|
|
|
222
222
|
### `server` — The dev server
|
|
223
223
|
|
|
224
|
-
| Field | Type | Default | Description
|
|
225
|
-
|
|
224
|
+
| Field | Type | Default | Description |
|
|
225
|
+
| -------------- | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
226
226
|
| `allowedHosts` | `string[] \| true` | `[]` | Host names the dev server answers besides `localhost`, `*.localhost` and IP addresses, as Vite's [`server.allowedHosts`](https://vite.dev/config/server-options#server-allowedhosts): `'my-app.ngrok.app'`, or `'.ngrok.app'` for the domain and its subdomains. `true` answers any host; avoid it |
|
|
227
227
|
|
|
228
228
|
A request whose `Host` is any other name gets 403: that is how DNS rebinding reaches a local server
|
|
@@ -257,27 +257,27 @@ export default defineConfig({
|
|
|
257
257
|
|
|
258
258
|
pp-dev validates your config at startup and reports problems clearly:
|
|
259
259
|
|
|
260
|
-
| Condition
|
|
261
|
-
|
|
262
|
-
| `mi.include` set + `mi.mode !== 'standalone'`
|
|
263
|
-
| `mi.url` missing + `mi.mode === 'embedding'` or `app.type === 'template'` | error
|
|
264
|
-
| `mi.url` missing + `mi.mode === 'standalone'` + `app.type === 'page'`
|
|
265
|
-
| `app.type === 'template'` without `app.id`
|
|
266
|
-
| `app.type === 'page'` + `mi.mode === 'standalone'` without `app.id`
|
|
267
|
-
| `app.name` missing and no `package.json#name`
|
|
268
|
-
| `devPanel.position` not one of the four corners
|
|
269
|
-
| `server.allowedHosts` neither a list of host names nor `true`
|
|
260
|
+
| Condition | Behaviour |
|
|
261
|
+
| ------------------------------------------------------------------------- | --------- |
|
|
262
|
+
| `mi.include` set + `mi.mode !== 'standalone'` | error |
|
|
263
|
+
| `mi.url` missing + `mi.mode === 'embedding'` or `app.type === 'template'` | error |
|
|
264
|
+
| `mi.url` missing + `mi.mode === 'standalone'` + `app.type === 'page'` | warning |
|
|
265
|
+
| `app.type === 'template'` without `app.id` | error |
|
|
266
|
+
| `app.type === 'page'` + `mi.mode === 'standalone'` without `app.id` | error |
|
|
267
|
+
| `app.name` missing and no `package.json#name` | error |
|
|
268
|
+
| `devPanel.position` not one of the four corners | error |
|
|
269
|
+
| `server.allowedHosts` neither a list of host names nor `true` | error |
|
|
270
270
|
|
|
271
271
|
### Environment Variables
|
|
272
272
|
|
|
273
|
-
| Variable
|
|
274
|
-
|
|
275
|
-
| `MI_ACCESS_TOKEN`
|
|
276
|
-
| `PP_DEV_DIST_ZIP`
|
|
277
|
-
| `PP_DEV_DIST_ZIP_DIR`
|
|
278
|
-
| `PP_DEV_DIST_ZIP_FILENAME`
|
|
279
|
-
| `PP_DEV_VERSION_MANIFEST`
|
|
280
|
-
| `PP_DEV_VERSION_FILE_TEMPLATE`
|
|
273
|
+
| Variable | Description |
|
|
274
|
+
| ------------------------------ | --------------------------------------------------------------------------------- |
|
|
275
|
+
| `MI_ACCESS_TOKEN` | Default value for `mi.token` when not set in config |
|
|
276
|
+
| `PP_DEV_DIST_ZIP` | `true`/`false` — override `build.zip` for `pp-dev build` / `pp-dev next-build` |
|
|
277
|
+
| `PP_DEV_DIST_ZIP_DIR` | Override the ZIP output directory (`build.zip.outDir`) |
|
|
278
|
+
| `PP_DEV_DIST_ZIP_FILENAME` | Override the ZIP file name (`build.zip.fileName`) |
|
|
279
|
+
| `PP_DEV_VERSION_MANIFEST` | `true`/`false` — override `build.versionFile` (VERSION/BUILD-MANIFEST generation) |
|
|
280
|
+
| `PP_DEV_VERSION_FILE_TEMPLATE` | Override the VERSION file name template |
|
|
281
281
|
|
|
282
282
|
The `PP_DEV_DIST_ZIP*`/`PP_DEV_VERSION_*` variables are read by `pp-dev build` and
|
|
283
283
|
`pp-dev next-build`; an equivalent CLI flag always takes precedence over its env var. See
|
|
@@ -298,40 +298,40 @@ npx @metricinsights/pp-dev migrate
|
|
|
298
298
|
|
|
299
299
|
Options:
|
|
300
300
|
|
|
301
|
-
| Option
|
|
302
|
-
|
|
303
|
-
| `[config]`
|
|
304
|
-
| `--dry-run`
|
|
305
|
-
| `--format ts\|js\|json` | Override output format
|
|
306
|
-
| `--output <file>`
|
|
307
|
-
| `--no-backup`
|
|
301
|
+
| Option | Description |
|
|
302
|
+
| ----------------------- | ----------------------------------------------- |
|
|
303
|
+
| `[config]` | Path to config file (auto-detected if omitted) |
|
|
304
|
+
| `--dry-run` | Preview the migrated output without writing |
|
|
305
|
+
| `--format ts\|js\|json` | Override output format |
|
|
306
|
+
| `--output <file>` | Write to a specific file instead of overwriting |
|
|
307
|
+
| `--no-backup` | Skip creating a `.bak` backup of the original |
|
|
308
308
|
|
|
309
309
|
The command detects flat 0.x configs and legacy `pp-watch.config.*` files, converts them to the new grouped format, and writes a `.bak` backup before overwriting.
|
|
310
310
|
|
|
311
311
|
**Field mapping** (0.x → 1.0):
|
|
312
312
|
|
|
313
|
-
| 0.x
|
|
314
|
-
|
|
315
|
-
| `backendBaseURL`
|
|
316
|
-
| `personalAccessToken`
|
|
317
|
-
| `miHudLess: true`
|
|
318
|
-
| `miHudLess: false`
|
|
319
|
-
| `integrateMiTopBar: true`
|
|
320
|
-
| `integrateMiTopBar: { addSharedComponentsScripts: true }` | `mi.include: 'shared-components'`
|
|
321
|
-
| `v7Features: true`
|
|
322
|
-
| `v7Features: false`
|
|
323
|
-
| `appId` / `portalPageId`
|
|
324
|
-
| `templateName`
|
|
325
|
-
| `templateLess: true`
|
|
326
|
-
| `templateLess: false`
|
|
327
|
-
| `enableProxyCache`
|
|
328
|
-
| `proxyCacheTTL`
|
|
329
|
-
| `disableSSLValidation: true`
|
|
330
|
-
| `distZip`
|
|
331
|
-
| `versionPlugin`
|
|
332
|
-
| `imageOptimizer`
|
|
333
|
-
| `outDir`
|
|
334
|
-
| `syncBackupsDir`
|
|
313
|
+
| 0.x | 1.0 |
|
|
314
|
+
| --------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
315
|
+
| `backendBaseURL` | `mi.url` |
|
|
316
|
+
| `personalAccessToken` | `mi.token` |
|
|
317
|
+
| `miHudLess: true` | `mi.mode: 'standalone'` |
|
|
318
|
+
| `miHudLess: false` | `mi.mode: 'embedding'` |
|
|
319
|
+
| `integrateMiTopBar: true` | `mi.mode: 'standalone'`, `mi.include: 'top-bar'` |
|
|
320
|
+
| `integrateMiTopBar: { addSharedComponentsScripts: true }` | `mi.include: 'shared-components'` |
|
|
321
|
+
| `v7Features: true` | `mi.apiVersion: 7` |
|
|
322
|
+
| `v7Features: false` | `mi.apiVersion: 6` |
|
|
323
|
+
| `appId` / `portalPageId` | `app.id` |
|
|
324
|
+
| `templateName` | `app.name` (usually omit — auto-resolved from `package.json#name`) |
|
|
325
|
+
| `templateLess: true` | `app.type: 'page'` |
|
|
326
|
+
| `templateLess: false` | `app.type: 'template'` |
|
|
327
|
+
| `enableProxyCache` | `proxy.cache` |
|
|
328
|
+
| `proxyCacheTTL` | `proxy.cacheTtl` |
|
|
329
|
+
| `disableSSLValidation: true` | `proxy.tls.allowSelfSigned: true` |
|
|
330
|
+
| `distZip` | `build.zip` |
|
|
331
|
+
| `versionPlugin` | `build.versionFile` |
|
|
332
|
+
| `imageOptimizer` | `build.imageOptimisations` |
|
|
333
|
+
| `outDir` | `build.outDir` |
|
|
334
|
+
| `syncBackupsDir` | `sync.backupsDir` |
|
|
335
335
|
|
|
336
336
|
## CLI Commands
|
|
337
337
|
|
|
@@ -374,13 +374,13 @@ pp-dev next [options]
|
|
|
374
374
|
# Aliases: pp-dev next-server, pp-dev next-dev
|
|
375
375
|
```
|
|
376
376
|
|
|
377
|
-
| Option | Default | Description
|
|
378
|
-
| --------------- | ----------- |
|
|
379
|
-
| `[root]` | `.` | Root directory of the application
|
|
380
|
-
| `--port <port>` | `3000` | Server port
|
|
381
|
-
| `--host [host]` | `localhost` | Server hostname; `--host` without a value listens on all addresses
|
|
382
|
-
| `--webpack` | - | Use Webpack for Next dev (when Turbopack/native SWC is unavailable)
|
|
383
|
-
| `--turbopack` | - | Use Turbopack for Next dev
|
|
377
|
+
| Option | Default | Description |
|
|
378
|
+
| --------------- | ----------- | ------------------------------------------------------------------- |
|
|
379
|
+
| `[root]` | `.` | Root directory of the application |
|
|
380
|
+
| `--port <port>` | `3000` | Server port |
|
|
381
|
+
| `--host [host]` | `localhost` | Server hostname; `--host` without a value listens on all addresses |
|
|
382
|
+
| `--webpack` | - | Use Webpack for Next dev (when Turbopack/native SWC is unavailable) |
|
|
383
|
+
| `--turbopack` | - | Use Turbopack for Next dev |
|
|
384
384
|
|
|
385
385
|
`--https`, `--open`, `--cors`, `--strictPort` and `--force` are accepted for compatibility but have no effect with `pp-dev next` (a warning says so); they will be removed.
|
|
386
386
|
|
|
@@ -390,18 +390,18 @@ pp-dev next [options]
|
|
|
390
390
|
pp-dev build [options]
|
|
391
391
|
```
|
|
392
392
|
|
|
393
|
-
| Option
|
|
394
|
-
|
|
|
395
|
-
| `[root]`
|
|
396
|
-
| `--target <target>`
|
|
397
|
-
| `--outDir <dir>`
|
|
398
|
-
| `--assetsDir <dir>`
|
|
399
|
-
| `--changelog [file]`
|
|
400
|
-
| `--distZip` / `--no-distZip`
|
|
401
|
-
| `--distZipDir <dir>`
|
|
402
|
-
| `--distZipFilename <file>`
|
|
393
|
+
| Option | Default | Description |
|
|
394
|
+
| -------------------------------------------- | --------- | -------------------------------------------------------------------- |
|
|
395
|
+
| `[root]` | `.` | Root directory of the application |
|
|
396
|
+
| `--target <target>` | `modules` | Transpile target |
|
|
397
|
+
| `--outDir <dir>` | `dist` | Output directory |
|
|
398
|
+
| `--assetsDir <dir>` | `assets` | Assets directory under outDir |
|
|
399
|
+
| `--changelog [file]` | `true` | Create changelog file |
|
|
400
|
+
| `--distZip` / `--no-distZip` | see below | Override `build.zip` — pack (or skip) the output ZIP |
|
|
401
|
+
| `--distZipDir <dir>` | see below | Override the ZIP output directory (`build.zip.outDir`) |
|
|
402
|
+
| `--distZipFilename <file>` | see below | Override the ZIP file name (`build.zip.fileName`) |
|
|
403
403
|
| `--versionManifest` / `--no-versionManifest` | see below | Override `build.versionFile` — emit (or skip) VERSION/BUILD-MANIFEST |
|
|
404
|
-
| `--versionFileTemplate <tpl>`
|
|
404
|
+
| `--versionFileTemplate <tpl>` | see below | Override the VERSION file name template |
|
|
405
405
|
|
|
406
406
|
The `--distZip*`/`--versionManifest*` flags (and their `PP_DEV_*` env var equivalents, see
|
|
407
407
|
[Environment Variables](#environment-variables)) let CI or ad-hoc builds override the `build.zip`
|
|
@@ -437,15 +437,15 @@ Use it in place of `next build` in your `package.json`:
|
|
|
437
437
|
}
|
|
438
438
|
```
|
|
439
439
|
|
|
440
|
-
| Option
|
|
441
|
-
|
|
|
442
|
-
| `[root]`
|
|
443
|
-
| `--changelog [file]`
|
|
444
|
-
| `--distZip` / `--no-distZip`
|
|
445
|
-
| `--distZipDir <dir>`
|
|
446
|
-
| `--distZipFilename <file>`
|
|
440
|
+
| Option | Default | Description |
|
|
441
|
+
| -------------------------------------------- | --------- | -------------------------------------------------------------------- |
|
|
442
|
+
| `[root]` | `.` | Root directory of the application |
|
|
443
|
+
| `--changelog [file]` | `true` | Create changelog file |
|
|
444
|
+
| `--distZip` / `--no-distZip` | see below | Override `build.zip` — pack (or skip) the output ZIP |
|
|
445
|
+
| `--distZipDir <dir>` | see below | Override the ZIP output directory (`build.zip.outDir`) |
|
|
446
|
+
| `--distZipFilename <file>` | see below | Override the ZIP file name (`build.zip.fileName`) |
|
|
447
447
|
| `--versionManifest` / `--no-versionManifest` | see below | Override `build.versionFile` — emit (or skip) VERSION/BUILD-MANIFEST |
|
|
448
|
-
| `--versionFileTemplate <tpl>`
|
|
448
|
+
| `--versionFileTemplate <tpl>` | see below | Override the VERSION file name template |
|
|
449
449
|
|
|
450
450
|
### Migration
|
|
451
451
|
|
|
@@ -453,13 +453,13 @@ Use it in place of `next build` in your `package.json`:
|
|
|
453
453
|
pp-dev migrate [config] [options]
|
|
454
454
|
```
|
|
455
455
|
|
|
456
|
-
| Option
|
|
457
|
-
|
|
458
|
-
| `[config]`
|
|
459
|
-
| `--dry-run`
|
|
460
|
-
| `--format ts\|js\|json` | Output format
|
|
461
|
-
| `--output <file>`
|
|
462
|
-
| `--no-backup`
|
|
456
|
+
| Option | Description |
|
|
457
|
+
| ----------------------- | ------------------------------------------------- |
|
|
458
|
+
| `[config]` | Config file to migrate (auto-detected if omitted) |
|
|
459
|
+
| `--dry-run` | Preview output without writing |
|
|
460
|
+
| `--format ts\|js\|json` | Output format |
|
|
461
|
+
| `--output <file>` | Write to a specific path |
|
|
462
|
+
| `--no-backup` | Skip `.bak` backup |
|
|
463
463
|
|
|
464
464
|
### Changelog Generation
|
|
465
465
|
|
|
@@ -558,8 +558,8 @@ Runtime choices are saved in the browser's `localStorage` (`pp-dev-info-position
|
|
|
558
558
|
export default defineConfig({
|
|
559
559
|
devPanel: {
|
|
560
560
|
position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
|
|
561
|
-
hidden: false,
|
|
562
|
-
autoHide: false,
|
|
561
|
+
hidden: false, // hide the panel entirely (restore with ?pp-dev-panel=show)
|
|
562
|
+
autoHide: false, // slide behind the screen edge, reveal on hover
|
|
563
563
|
},
|
|
564
564
|
});
|
|
565
565
|
```
|
|
@@ -583,7 +583,7 @@ A standalone page at `/@pp-dev/variables-editor`, alongside the [Request Inspect
|
|
|
583
583
|
|
|
584
584
|
|
|
585
585
|
|
|
586
|
-
- **Values** — edit the page's live variable values in place, with type-aware widgets (searchable select for `static` options, a per-item form for `list`, …). A JSON mode (`View/edit raw JSON`) shows/accepts the same values as plain JSON — list-type values as native arrays, not double-escaped strings — with **Save to JSON file…** / **Import from JSON file…** buttons, and flags values that don't match a declared option, changed since the last load, or aren't in the schema. Each variable's description is shown as markdown, the way MI renders it: **bold**,
|
|
586
|
+
- **Values** — edit the page's live variable values in place, with type-aware widgets (searchable select for `static` options, a per-item form for `list`, …). A JSON mode (`View/edit raw JSON`) shows/accepts the same values as plain JSON — list-type values as native arrays, not double-escaped strings — with **Save to JSON file…** / **Import from JSON file…** buttons, and flags values that don't match a declared option, changed since the last load, or aren't in the schema. Each variable's description is shown as markdown, the way MI renders it: **bold**, _italic_, `code` and fenced code blocks, lists, and `<u>` / `<s>` / `<del>` for underline and strikethrough.
|
|
587
587
|
|
|
588
588
|
The pages the dev server serves substitute `[VarName]` from its own copy of the values, loaded from MI with the page data. **Save** updates that copy too, so every tab (any user) shows the saved values on its next load. When the values in MI change some other way (edited in MI itself, or the update after a save failed), the Values tab shows **Update local pages · N** in its bottom-right corner; its tooltip lists the values that differ, and a click updates the copy.
|
|
589
589
|
|
|
@@ -617,7 +617,7 @@ Every saved user gets its own host: `<name>.localhost:<port>`. The browser sends
|
|
|
617
617
|
### Adding users
|
|
618
618
|
|
|
619
619
|
- **API token**: the token is checked with MI before the user is added. SSO users can only be added this way.
|
|
620
|
-
- **Username + password** (local MI users): pp-dev adds the user and opens MI's usual login page on the user's own host. You log in there as in MI — 2FA included — and pp-dev never sees the password. Until then the user is
|
|
620
|
+
- **Username + password** (local MI users): pp-dev adds the user and opens MI's usual login page on the user's own host. You log in there as in MI — 2FA included — and pp-dev never sees the password. Until then the user is _not logged in yet_; once MI ends the session it is _session expired_ and **Log in** opens the login page again.
|
|
621
621
|
|
|
622
622
|
The name becomes the user's host, so it may contain only lowercase latin letters, digits and `-`, must start with a letter and be at most 32 characters long.
|
|
623
623
|
|
|
@@ -629,7 +629,7 @@ Logging out on a user's host ends that user's MI session (or token) as it would
|
|
|
629
629
|
|
|
630
630
|
### Keeping users between runs
|
|
631
631
|
|
|
632
|
-
Users live as long as the dev server. With `users: { persist: true }` the users added with an API token are kept in `~/.pp-dev/users/<hash>.json` — one file per project and MI instance, outside the project so it never ends up in git or a build. The tokens are stored as plain text: on macOS and Linux the file is readable by you only (mode `0600`); Windows ignores file modes, so there it is as private as your user profile folder (by default readable by you, administrators and the system). Two dev servers on the same project and MI instance share the file: each keeps the users the other added. Passwords and MI sessions are never written. On start, every kept token is checked with MI again; one MI turns down shows as
|
|
632
|
+
Users live as long as the dev server. With `users: { persist: true }` the users added with an API token are kept in `~/.pp-dev/users/<hash>.json` — one file per project and MI instance, outside the project so it never ends up in git or a build. The tokens are stored as plain text: on macOS and Linux the file is readable by you only (mode `0600`); Windows ignores file modes, so there it is as private as your user profile folder (by default readable by you, administrators and the system). Two dev servers on the same project and MI instance share the file: each keeps the users the other added. Passwords and MI sessions are never written. On start, every kept token is checked with MI again; one MI turns down shows as _API token turned down by MI_.
|
|
633
633
|
|
|
634
634
|
```typescript
|
|
635
635
|
// pp-dev.config.ts
|
|
@@ -644,13 +644,13 @@ export default defineConfig({
|
|
|
644
644
|
|
|
645
645
|
The popover uses a small JSON API:
|
|
646
646
|
|
|
647
|
-
| Method | Path
|
|
648
|
-
|
|
649
|
-
| `GET` | `/@api/users`
|
|
650
|
-
| `POST` | `/@api/users`
|
|
651
|
-
| `PUT` | `/@api/users/default`
|
|
652
|
-
| `PATCH` | `/@api/users/:name`
|
|
653
|
-
| `DELETE` | `/@api/users/:name`
|
|
647
|
+
| Method | Path | Description |
|
|
648
|
+
| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
649
|
+
| `GET` | `/@api/users` | The users (name, kind, state, MI user, `origin`, `loginUrl`), the default user, and whether users are available |
|
|
650
|
+
| `POST` | `/@api/users` | Add a user: `{ "name", "token" }`, or `{ "name", "kind": "session" }` to log in with a password |
|
|
651
|
+
| `PUT` | `/@api/users/default` | Make a user the default: `{ "name" }`, or `{ "name": null }` for you |
|
|
652
|
+
| `PATCH` | `/@api/users/:name` | Edit a user added with an API token: `{ "name" }` to rename it, `{ "token" }` to replace its token |
|
|
653
|
+
| `DELETE` | `/@api/users/:name` | Remove a user |
|
|
654
654
|
|
|
655
655
|
Tokens and MI sessions are never sent back.
|
|
656
656
|
|
|
@@ -673,17 +673,18 @@ Open `http://localhost:3000/@pp-dev/inspector` (replace port as needed) in any b
|
|
|
673
673
|
Selecting a request opens the detail pane with headers and a syntax-highlighted body:
|
|
674
674
|
|
|
675
675
|
|
|
676
|
+
|
|
676
677
|
- A **Clear** button in the top-right removes all stored entries
|
|
677
678
|
|
|
678
679
|
### Source badges
|
|
679
680
|
|
|
680
681
|
Each request in the list displays a colored letter badge to the left of the HTTP status:
|
|
681
682
|
|
|
682
|
-
| Badge | Color | Meaning
|
|
683
|
-
|
|
683
|
+
| Badge | Color | Meaning |
|
|
684
|
+
| ----- | ------ | -------------------------------------------------------- |
|
|
684
685
|
| `P` | Purple | Forwarded to the upstream Metric Insights server (proxy) |
|
|
685
|
-
| `C` | Amber | Served from the local proxy cache
|
|
686
|
-
| `L` | Grey | Served locally (static file, dev route, etc.)
|
|
686
|
+
| `C` | Amber | Served from the local proxy cache |
|
|
687
|
+
| `L` | Grey | Served locally (static file, dev route, etc.) |
|
|
687
688
|
|
|
688
689
|
### Console banner
|
|
689
690
|
|
|
@@ -699,12 +700,12 @@ The message persists in DevTools history so it is visible even when you open the
|
|
|
699
700
|
|
|
700
701
|
The inspector also exposes a lightweight JSON API, useful for tooling and AI agents:
|
|
701
702
|
|
|
702
|
-
| Method | Path
|
|
703
|
-
|
|
704
|
-
| `GET` | `/@api/requests`
|
|
705
|
-
| `GET` | `/@api/requests/:id`
|
|
706
|
-
| `GET` | `/@api/requests/stats`
|
|
707
|
-
| `DELETE` | `/@api/requests`
|
|
703
|
+
| Method | Path | Description |
|
|
704
|
+
| -------- | ---------------------- | ---------------------------------------------------------------------- |
|
|
705
|
+
| `GET` | `/@api/requests` | Paginated list of captured requests (metadata only, no bodies) |
|
|
706
|
+
| `GET` | `/@api/requests/:id` | Full entry including captured request/response bodies (base64-encoded) |
|
|
707
|
+
| `GET` | `/@api/requests/stats` | Store stats: entry count, memory usage, limits |
|
|
708
|
+
| `DELETE` | `/@api/requests` | Clear all stored entries |
|
|
708
709
|
|
|
709
710
|
`GET /@api/requests` accepts `?limit=` (default 50) and `?offset=` query parameters for pagination.
|
|
710
711
|
|
|
@@ -716,8 +717,8 @@ Bodies in `GET /@api/requests/:id` are returned as base64 strings in `requestBod
|
|
|
716
717
|
// pp-dev.config.ts
|
|
717
718
|
export default defineConfig({
|
|
718
719
|
inspector: {
|
|
719
|
-
enabled: true,
|
|
720
|
-
maxMemory: 100 * 1024 * 1024,
|
|
720
|
+
enabled: true, // set to false to disable entirely
|
|
721
|
+
maxMemory: 100 * 1024 * 1024, // evict oldest entries above 100 MB
|
|
721
722
|
captureLimit: 10 * 1024 * 1024, // capture at most 10 MB per body
|
|
722
723
|
},
|
|
723
724
|
});
|
|
@@ -754,7 +755,7 @@ If you encounter an error like "Next.js is required but not available":
|
|
|
754
755
|
|
|
755
756
|
#### Version Compatibility
|
|
756
757
|
|
|
757
|
-
- **pp-dev**
|
|
758
|
+
- **pp-dev** accepts Next.js 13 to 16 (`>= 13 < 17`); the test apps run on Next.js 16
|
|
758
759
|
- **Node.js** version 24 or higher is required
|
|
759
760
|
- **TypeScript** version 5 or higher is recommended
|
|
760
761
|
|