pipedrive-add-app-extension

name	pipedrive-add-app-extension
description	Add a custom panel or custom modal App Extension to an existing Pipedrive integration project. Use when the developer wants to add an iframe-based UI extension to their app.
allowed-tools	["Bash","Read","Edit"]

Add App Extension to Existing Project

App Extensions background

Pipedrive App Extensions let your app embed custom web content as an iframe directly inside Pipedrive's UI. The two types supported by this tool are:

Custom panel — an iframe embedded in the sidebar of deal, person, and organization detail views. Use this when you want to show contextual data from your app alongside a Pipedrive record.

Custom modal — an iframe opened as a modal from Pipedrive menus or triggered by a panel action. Use this for workflows that require user input or actions (e.g. creating a record in your app from Pipedrive).

Both types require the @pipedrive/app-extensions-sdk in the iframe. The SDK handles:

• Initialisation and receiving the signed JWT token identifying the current user and company
• Theme synchronisation (light/dark)
• Iframe resize
• Snackbar notifications
• Confirmation dialogs
• Panel → modal navigation (open a modal from a panel)

Full documentation: https://pipedrive.readme.io/docs/app-extensions

Preconditions

1. Check that package.json exists in the current directory. If it does not, tell the developer to run this command from their project root and stop.
2. Check which extension types already exist:
   • Panel: src/app-extensions/panel/index.ts
   • Modal: src/app-extensions/modal/index.ts
3. If both already exist, tell the developer both extension types are already set up and stop.

Generation

Ask the developer which extension type they want to add (custom-panel or custom-modal). If one type already exists, only offer the other.

Run the CLI subcommand with the chosen type:

npx create-pipedrive-app add-app-extension --app-extensions custom-panel
# or
npx create-pipedrive-app add-app-extension --app-extensions custom-modal

If the command exits with a non-zero code, report the error and stop.

Wire router into src/app.ts

Read src/app.ts. For a custom-panel addition:

1. Add this import near the other router imports:

   import panelRouter from './app-extensions/panel/index.js';
   

2. Add this router mount before the error handler:

   app.use('/extensions/panel', panelRouter);
   

For a custom-modal addition, use modalRouter and /extensions/modal instead.

Wire React snippets into frontend

Read frontend/app-extension-ui/src/main.tsx. If the App Extensions frontend already exists (the developer added the other extension type earlier), update the routing to include the new extension type. If the frontend does not exist, it was just generated by the CLI — no further action needed.

Update docker-compose.yml

Read docker-compose.yml. If it does not already contain an app-extension-ui service, add it under services: and add app_extension_ui_node_modules: under volumes::

services:
  app-extension-ui:
    build:
      context: .
      dockerfile: Dockerfile.app-extension-ui
    user: root
    command: sh -c "chown -R node:node /app/node_modules && su-exec node sh -c 'echo Installing dependencies... && npm install --no-package-lock --no-audit --no-fund --loglevel=error && npm run dev:frontend'"
    environment:
      CHOKIDAR_USEPOLLING: "true"
    ports:
      - "5173:5173"
    volumes:
      - ./package.json:/app/package.json:ro
      - app_extension_ui_node_modules:/app/node_modules
    develop:
      watch:
        - action: sync
          path: ./frontend/app-extension-ui
          target: /app/frontend/app-extension-ui
          initial_sync: true
          ignore:
            - node_modules/
            - dist/
        - action: rebuild
          path: ./package.json

volumes:
  app_extension_ui_node_modules:

Also create Dockerfile.app-extension-ui in the project root if it does not exist:

FROM node:24-alpine

RUN apk add --no-cache su-exec
WORKDIR /app
ENV NPM_CONFIG_USERCONFIG=/tmp/.npmrc
RUN mkdir -p /app/node_modules && chown -R node:node /app
USER node
RUN npm config set registry https://registry.npmjs.org/

COPY --chown=node:node package.json ./
COPY --chown=node:node frontend/app-extension-ui ./frontend/app-extension-ui

EXPOSE 5173
CMD ["npm", "run", "dev:frontend"]

Report to developer

Tell the developer:

• The files that were added
• To expose the Vite server (port 5173) via a public HTTPS tunnel for local development
• To set the tunnel URL as the iframe URL in the Pipedrive Developer Hub for this extension type:
  • Custom panel: https://<your-vite-tunnel>/extensions/panel
  • Custom modal: https://<your-vite-tunnel>/extensions/modal
• In production, npm run build compiles the Vite frontend and the backend serves it at /extensions/panel or /extensions/modal
• Link to documentation: https://pipedrive.readme.io/docs/app-extensions