pp-dev

The PP Dev Helper is a development framework and build tool for Metric Insights' Portal Pages, designed to make the
lives of PP developers easier:

- Build and test Portal Pages locally
- Proxy API requests to a Metric Insights server
- Hot module replacement for faster development
- Image optimization and asset management
- Template variable transformation
- Code synchronization with Metric Insights instances

pp-dev is based on Vite.

Installation

``bash
npm install @metricinsights/pp-dev
`

$3

This package requires Next.js as a peer dependency for certain functionality:

`bash
npm install next@^15
`

Note: pp-dev requires Next.js version 15 or higher (but less than 17) to be installed in your project. This is a peer dependency, meaning it won't be automatically installed with pp-dev.

Package Structure

The pp-dev package provides multiple entry points for different use cases:

`javascript
// Main package (includes everything)
import ppDev from '@metricinsights/pp-dev';

// Plugin only (for Vite integration)
import { vitePPDev } from '@metricinsights/pp-dev/plugin';

// Helpers only (for utility functions)
import { helpers } from '@metricinsights/pp-dev/helpers';

// Client assets (for development UI)
import '@metricinsights/pp-dev/client/css/client.css';
`

Available Exports:
- Main: Complete pp-dev functionality with CLI and plugins
- Plugin: Vite plugin for integration with build tools
- Helpers: Utility functions for authentication and configuration
- Client: Development UI assets and styles

🚀 Performance & Build System

The pp-dev package includes optimized startup performance and build system with multiple strategies:

$3

Run the startup optimizer to analyze and improve your development environment:
`bash
npm run startup:optimize
`

📖 See BUILD_IMPROVEMENTS.md for build details.
📖 See STARTUP_PERFORMANCE.md for performance details.

Configuration

$3

Create a configuration file named pp-dev.config with one of these extensions:
- .js or .cjs (for CommonJS)
- .ts (for TypeScript)
- .json

Alternatively, you can define configuration in your package.json using the pp-dev key.

$3

#### JavaScript (CommonJS)

`javascript
// pp-dev.config.js

/**
* @type {import('@metricinsights/pp-dev').PPDevConfig}
*/
module.exports = {
backendBaseURL: 'https://mi.company.com',
appId: 1,
v7Features: true,
miHudLess: true,
integrateMiTopBar: true,
};
`

#### TypeScript

`typescript
// pp-dev.config.ts

import { PPDevConfig } from '@metricinsights/pp-dev';

const config: PPDevConfig = {
backendBaseURL: 'https://mi.company.com',
appId: 1,
v7Features: true,
miHudLess: true,
integrateMiTopBar: true,
};

export default config;
`

#### JSON

`json
// pp-dev.config.json
{
"backendBaseURL": "https://mi.company.com",
"appId": 1,
"v7Features": true,
"miHudLess": true,
"integrateMiTopBar": true
}
`

#### package.json

`json
{
"name": "my-portal-page",
"version": "1.0.0",
"pp-dev": {
"backendBaseURL": "https://mi.company.com",
"appId": 1,
"v7Features": true,
"miHudLess": true,
"integrateMiTopBar": true
}
}
`

Configuration Options

> Version Compatibility: This documentation covers pp-dev v0.11.0+. Some options may not be available in older versions. Check the CHANGELOG for version-specific information.

$3

| Option | Type | Description |
|--------|------|-------------|
| backendBaseURL | string | URL of the Metric Insights instance for API proxying |
| portalPageId | number | ID of the Portal Page for variable values (deprecated, use appId instead) |
| appId | number | ID of the Portal Page for variable values (synonym for portalPageId) |

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| miHudLess | boolean | false | Disables Metric Insights navigation bar in development |
| integrateMiTopBar | boolean \| object | false | Integrates MI Top Bar and scripts into the App build (requires miHudLess: true). When true, enables both addRootElement and addSharedComponentsScripts. When an object, allows selective enabling: { addRootElement?: boolean, addSharedComponentsScripts?: boolean } |
| templateLess | boolean | false | Disables template variable transformation |
| enableProxyCache | boolean | true | Enables caching of proxied requests |
| proxyCacheTTL | number | 600000 | Cache TTL in milliseconds (10 minutes) |
| disableSSLValidation | boolean | false | Disables SSL certificate validation for proxy requests |
| imageOptimizer | boolean \| object | true | Controls image optimization. See vite-plugin-image-optimizer for object options |
| outDir | string | dist | Output directory for builds |
| distZip | boolean \| object | true | Controls build output zipping. Object options: { outDir?: string, outFileName?: string } |
| syncBackupsDir | string | backups | Directory for asset backups from MI server |
| v7Features | boolean | false | Enables Metric Insights v7 features |
| personalAccessToken | string | process.env.MI_ACCESS_TOKEN | Personal Access Token for the MI instance |

$3

The integrateMiTopBar option allows you to integrate the Metric Insights Top Bar and scripts directly into your application build. This is useful when you want to:

1. Customize the Top Bar: Modify the appearance and behavior of the MI navigation
2. Bundle Integration: Include MI scripts in your build instead of loading them dynamically
3. Offline Development: Work with MI features even when disconnected from the server

Important: This option can only be enabled when miHudLess is set to true.

#### Configuration Options

integrateMiTopBar can be configured in two ways:

1. Boolean (Simple)
- true: Enables both addRootElement and addSharedComponentsScripts
- false: Disables integration (default)

2. Object (Advanced)
- addRootElement: Adds