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

npm install @metricinsights/pp-dev

Peer Dependencies

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

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:

// 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:

Quick Start

# Standard build (parallel)
npm run build

# Fast development build
npm run build:fast

# Watch mode for development
npm run build:watch

# Bundle analysis
npm run build:analyze

# Performance profiling
npm run startup:profile

# Startup optimization
npm run startup:optimize

Performance Features

40-50% faster startup with intelligent caching
60-70% faster subsequent starts with connection pooling
Lazy loading of heavy modules (jsdom, esbuild)
API response caching with configurable TTL
HTTP connection pooling for reduced overhead
Startup profiling with detailed performance analysis
Intelligent dependency optimization based on profiling data

Build Features

Parallel builds for 40-60% faster build times
Enhanced tree-shaking for smaller bundles
Multiple output formats (ESM, CJS, Types)
Bundle analysis with visualizer support
ESBuild integration for faster TypeScript compilation
Build optimization scripts for performance tuning

Startup Optimization

The new startup optimization system in v0.11.0 provides:

Performance Monitoring: Real-time startup time tracking and analysis
Cache Optimization: Intelligent cache management for config and API responses
Dependency Analysis: Identification of performance bottlenecks
Optimization Suggestions: Automated recommendations for performance improvements

Run the startup optimizer to analyze and improve your development environment:

npm run startup:optimize

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

Configuration

Configuration File

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.

Configuration Examples

JavaScript (CommonJS)

// 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

// 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

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

package.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.

Required Options

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`)

Optional Options

Option	Type	Default	Description
`miHudLess`	boolean	`false`	Disables Metric Insights navigation bar in development
`integrateMiTopBar`	boolean	`false`	Integrates MI Top Bar and script into the App build (requires `miHudLess: true`)
`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

integrateMiTopBar Details

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:

Customize the Top Bar: Modify the appearance and behavior of the MI navigation
Bundle Integration: Include MI scripts in your build instead of loading them dynamically
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.

Example configuration:

// pp-dev.config.js
module.exports = {
  backendBaseURL: 'https://mi.company.com',
  appId: 1,
  miHudLess: true,           // Required: Disable dynamic MI scripts
  integrateMiTopBar: true,    // Enable: Integrate Top Bar into build
};

v7Features Details

When enabled (true), this option:

Changes development path from /pt/<portal-page-name> to /pl/<portal-page-name>
Updates Code Sync feature to use v7.1.0+ URLs

Personal Access Token

The personalAccessToken option allows you to authenticate with the Metric Insights instance. You can set it in your configuration or use the MI_ACCESS_TOKEN environment variable.

Example with authentication and Top Bar integration:

// pp-dev.config.js
module.exports = {
  backendBaseURL: 'https://mi.company.com',
  appId: 1,
  personalAccessToken: process.env.MI_ACCESS_TOKEN,
  miHudLess: true,
  integrateMiTopBar: true,
};

Environment Variable: Set MI_ACCESS_TOKEN in your .env file:

MI_ACCESS_TOKEN=your_token_here

Enhanced Authentication (v0.11.0+)

The new authentication system in v0.11.0 provides:

Automatic Environment Loading: Automatically loads MI_* environment variables from .env files
Token Validation: Enhanced token validation and error handling
Secure Headers: Automatic header management for authenticated requests
Connection Pooling: Optimized HTTP connections for better performance

Supported Environment Variables:

MI_ACCESS_TOKEN: Personal access token for authentication
MI_BACKEND_URL: Alternative to backendBaseURL in config
MI_APP_ID: Alternative to appId in config

Automatic Loading: pp-dev automatically detects and loads these variables from your project's .env file:

# .env
MI_ACCESS_TOKEN=your_personal_access_token
MI_BACKEND_URL=https://mi.company.com
MI_APP_ID=123

CLI Commands

Global Options

Option	Description
`-c, --config <file>`	Path to configuration file (default: `pp-dev.config.js`)
`--base <path>`	Public base path (default: `/`)
`-l, --logLevel <level>`	Log level: `trace`, `debug`, `info`, `warn`, `error`, `silent` (default: `info`)
`--clearScreen`	Clear screen before logging
`--mode <mode>`	Environment mode: `development`, `production`, `test` (default: `development`)

Development Server

pp-dev [root] [options]
# Aliases: pp-dev dev, pp-dev serve

Option	Default	Description
`[root]`	`.`	Root directory of the application
`--host <host>`	`localhost`	Server hostname
`--port <port>`	`3000`	Server port
`--open [path]`	-	Open browser on server start
`--strictPort`	-	Exit if port is already in use

Development Shortcuts:

p - Start/stop performance profiler (v0.11.0+)
l - Proxy re-login (refresh authentication)
r - Restart dev server
u - Show server URLs
q - Quit dev server

Performance Profiling: Use the p shortcut to start/stop the Node.js profiler for detailed performance analysis during development.

Next.js Development

pp-dev next [options]
# Aliases: pp-dev next-server, pp-dev next-dev

Option	Default	Description
`[root]`	`.`	Root directory of the application
`--port <port>`	`3000`	Server port
`--host <host>`	`localhost`	Server hostname

Build

pp-dev build [options]

Option	Default	Description
`[root]`	`.`	Root directory of the application
`--target <target>`	`modules`	Transpile target
`--outDir <dir>`	`dist`	Output directory
`--assetsDir <dir>`	`assets`	Assets directory under outDir
`--changelog [file]`	`true`	Create changelog file

Changelog Generation

pp-dev changelog [oldAssetPath] [newAssetPath] [options]

Option	Default	Description
`[oldAssetPath]`	-	Path to previous assets
`[newAssetPath]`	-	Path to current assets
`--oldAssetsPath <path>`	-	Path to previous assets
`--newAssetsPath <path>`	-	Path to current assets
`--destination <path>`	`.`	Changelog output directory
`--filename <name>`	`CHANGELOG.html`	Changelog filename

Icon Font Generation

pp-dev generate-icon-font [source] [destination] [options]

Option	Default	Description
`[source]`	-	Source directory with SVG icons
`[destination]`	-	Output directory
`--source <path>`	-	Source directory with SVG icons
`--destination <path>`	-	Output directory
`--fontName <name>`	`icon-font`	Font name

Next.js Integration

Add pp-dev configuration to your project root

Update package.json scripts:

{
  "scripts": {
    "dev": "pp-dev next"
  }
}

Wrap your Next.js config:

// next.config.js
const { withPPDev } = require('@metricinsights/pp-dev');

module.exports = withPPDev({
     // your Next.js config
});

Vite Configuration

For custom build configuration, create a vite.config file. See Vite Configuration for details.

Troubleshooting

Common Issues

Next.js Peer Dependency Error

If you encounter an error like "Next.js is required but not available":

Install Next.js in your project:
```
npm install next@^15
```
Verify the installation:
```
npm list next
```

Check your package.json:

{
  "dependencies": {
    "next": "^15.0.0"
  }
}

Version Compatibility

pp-dev requires Next.js version 15 or higher (but less than 17)
Node.js version 20 or higher is required
TypeScript version 4.2 or higher is supported

Getting Help

Check the GitHub Issues for known problems
Review the CHANGELOG.md for recent changes
Ensure all peer dependencies are properly installed

Navigation Menu

Uh oh!

pp-dev

Installation

Peer Dependencies

Package Structure

🚀 Performance & Build System

Quick Start

Performance Features

Build Features

Startup Optimization

Configuration

Configuration File

Configuration Examples

JavaScript (CommonJS)

TypeScript

JSON

package.json

Configuration Options

Required Options

Optional Options

integrateMiTopBar Details

v7Features Details

Personal Access Token

Enhanced Authentication (v0.11.0+)

CLI Commands

Global Options

Development Server

Next.js Development

Build

Changelog Generation

Icon Font Generation

Next.js Integration

Vite Configuration

Troubleshooting

Common Issues

Next.js Peer Dependency Error

Version Compatibility

Getting Help

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

pp-dev

Installation

Peer Dependencies

Package Structure

🚀 Performance & Build System

Quick Start

Performance Features

Build Features

Startup Optimization

Configuration

Configuration File

Configuration Examples

JavaScript (CommonJS)

TypeScript

JSON

package.json

Configuration Options

Required Options

Optional Options

integrateMiTopBar Details

v7Features Details

Personal Access Token

Enhanced Authentication (v0.11.0+)

CLI Commands

Global Options

Development Server

Next.js Development

Build

Changelog Generation

Icon Font Generation

Next.js Integration

Vite Configuration

Troubleshooting

Common Issues

Next.js Peer Dependency Error

Version Compatibility

Getting Help