@metricinsights/pp-dev v0.10.1

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

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',
  portalPageId: 1,
};

TypeScript

// pp-dev.config.ts

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

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

export default config;

JSON

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

package.json

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

Configuration Options

Required Options

Optional Options

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:

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

CLI Commands

Global Options

Development Server

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

Next.js Development

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

Build

pp-dev build [options]

Changelog Generation

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

Icon Font Generation

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

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.