pipedrive-add-app-extension

name	pipedrive-add-app-extension
description	Add custom panel or modal App Extensions. Use when embedding iframe UI in Pipedrive records or menus.
allowed-tools	["Bash","Read","Edit"]

Add App Extension to Existing Project

App Extensions background

Pipedrive App Extensions embed iframe UI inside Pipedrive:

• Custom panel: sidebar iframe on deal, person, and organization detail views.
• Custom modal: menu-opened or panel-triggered modal iframe for user workflows.

Both use @pipedrive/app-extensions-sdk for signed user/company JWTs, theme sync, iframe resizing, snackbars, confirmations, and panel-to-modal navigation.

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