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:

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.

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:

1. Changes development path from /pt/<portal-page-name> to /pl/<portal-page-name>
2. 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

1. Add pp-dev configuration to your project root
2. Update package.json scripts:

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

3. 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":

1. Install Next.js in your project:

   npm install next@^15

2. Verify the installation:

   npm list next

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