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 your Portal Page
run/test locally with API requests proxied to a Metric Insights server
a lot more (to be documented soon!)

pp-dev is based on Vite.

Usage

Package installation

$ npm i @metricinsights/pp-dev

Define Configuration

You'll need to create a file with the name pp-dev.config and extension js or cjs (if you define type module in package.json), or ts if you want to use TypeScript, or json.

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

Generic configuration examples:

JavaScript

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

export default config;

JSON as pp-dev.config.json

{
  "backendBaseURL": "https://mi.company.com",
  "portalPageId": 1
}

JSON as package.json

{
  "name": "<project-name>",
  "version": "1.0.0",
  "scripts": {},
  "pp-dev": {
    "backendBaseURL": "https://mi.company.com",
    "portalPageId": 1
  }
}

Next.js Configuration

To use the PP Dev Helper with Next.js:

Add pp-dev config to your root directory.
Change your dev script in package.json to pp-dev next.
Finally, wrap your next.config with a withPPDev function.

// next.config.js

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

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

Vite configuration

If you need to change something in the build you can define a vite.config file. More details Vite Confighere

Configuration API description

`backendBaseURL`

Type: String

Example: https://mi.company.com

Description: Defines the backend URL (Metric Insights instance) that is used for proxying requests to the MI backend

`portalPageId`

Type: Number

Example: 1

Description: Defines the Portal Page ID that used to get Portal Page Variable values.

`miHudLess`

Type: Boolean

Default: false

Example: true

Description: Disables Metric Insights navigation bar for local development

`templateLess`

Type: Boolean

Default: false

Example: true

Description: Disables Template Variables transformation. Used when developing a Portal Page without a template

`enableProxyCache`

Type: Boolean

Default: true

Description: Enables proxy cache. If you want to disable proxy cache, you need to set this option to false

`proxyCacheTTL`

Type: Number

Default: 10 * 60 * 1000

Description: Defines proxy cache TTL in milliseconds

`disableSSLValidation`

Type: Boolean

Default: false

Description: Disables SSL certificate validation for proxy requests. Useful for self-signed certificates

`imageOptimizer`

Type: Boolean | Object

Default: true

Description: Enables image optimization for build. If you want to disable image optimization, you need to set this option to false. If you want to customize image optimization, you need to set this option to an object with properties that are described in the vite-plugin-image-optimizer

`outDir`

Type: String

Default: dist

Description: Define the output directory for the build

`distZip`

Type: Boolean | { outDir?: string, outFileName?: string }

Default: true

Description: Enables zipping the build output. If you want to disable zipping the build output, you need to set this option to false. If you want to customize zipping the build output, you need to set this option to an object with properties outDir and outFileName.

outDir defines the output directory for the zipped build.
outFileName defines the output file name for the zipped build. You can use placeholder [templateName] in the file name to replace it with the template name.

`syncBackupsDir`

Type: String

Default: backups

Description: Define the directory for the asset backups that are used for backup assets from the MI server

CLI API description

pp-dev help - show CLI's help

Global options:

-c, --config <configFile> - define the path to the configuration file. Default is pp-dev.config.js
--base <path> - public base path (default: /)
-l, --logLevel <level> - define the log level. Default is info. Available options: trace, debug, info, warn, error, silent
--clearScreen - clear the screen before logging
--mode <mode> - define the environment mode. Default is development. Available options: development, production, test