PropVault CMS — Plugin Development Kit (PDK)

Extend the functionality of the PropVault Real Estate CMS and Page Builder platform with dynamic plugins. Custom plugins can register Action hooks to trigger custom logic on events (e.g. sending CRM leads) and Filter hooks to intercept and mutate variables/configs before operations complete.

Getting Started

1. Requirements

Ensure you have Node.js >= 18 and TypeScript installed locally.

2. Scaffold a New Plugin

Run the PDK CLI initializer inside the directory where you want to scaffold your plugin.

# Initialize a new plugin template
npx @vikukumar/propvault-pdk create my-custom-plugin

This scaffolds the following plugin directory structure:

my-custom-plugin/
├── src/
│   └── index.ts          # Core plugin logic & hooks registration
├── dist/                 # Compiled distribution (created on build)
├── package.json          # Node config & build scripts
├── tsconfig.json         # TypeScript compiler configurations
└── plugin.json           # Plugin manifest metadata block

3. Install Scaffolding Dependencies

cd my-custom-plugin
npm install

Writing Plugin Logic

Plugins register hook handlers inside src/index.ts using addAction and addFilter from the @vikukumar/propvault-pdk package.

1. Action Hooks

Action hooks trigger custom operations when specific system events occur (e.g., lead submission, newsletter registration, theme swap).

import { addAction } from "@vikukumar/propvault-pdk";

// Send WhatsApp telemetry notifications on new lead submissions
addAction("after_lead_submit", async (lead: any) => {
  console.log("New Lead submitted in CMS:", lead.email);
  
  // Call webhook endpoint
  await fetch("https://api.mycrm.com/v1/leads", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(lead),
  });
}, 10);

2. Filter Hooks

Filter hooks intercept, modify, and return modified values/variables before the CMS processes them.

import { addFilter } from "@vikukumar/propvault-pdk";

// Force a premium badge suffix on project titles before they are stored in the database
addFilter("before_project_save", async (project: any) => {
  if (project.title && !project.title.includes("[Verified]")) {
    project.title = `${project.title} [Verified]`;
  }
  return project;
});

Core Hooks Registry API

Action Hooks

| Hook Slug | Arguments | Description | |---|---|---| | after_lead_submit | (lead: Lead) | Fires after a contact form submission is registered. | | after_newsletter_subscribe | (subscription: Subscription) | Fires after a newsletter email subscription is verified. |

Filter Hooks

| Hook Slug | Arguments | Description | |---|---|---| | before_project_save | (project: Project) | Filters project attributes before SQLite/PostgreSQL insertion. | | before_lead_save | (lead: Lead) | Filters lead fields before database submission. |

Build & Packaging

Once development is complete, compile and compress your plugin files into a distribution-ready bundle:

# 1. Compile TypeScript to JavaScript dist/index.js
npm run build

# 2. Package manifest and built script into plugin.zip
npm run package

The CLI outputs a plugin.zip package.

Publishing and Installation Options

PropVault CMS supports three installation pathways:

Option A: Direct Zip Upload (Recommended)

1. Go to PropVault Admin Panel -> Plugins.
2. Locate the Upload Zip Archive card.
3. Select your built plugin.zip file.
4. Click Upload and toggle Activate.

Option B: Package Manager (NPM Release)

Publish your compiled folder structure containing plugin.json to npm:

npm publish

CMS administrators can install it in their workspace by entering the package name (e.g. my-propvault-plugin) in the NPM Package Registry dashboard card.

Option C: Git Releases

Host your plugin repository on GitHub/GitLab. Make sure it contains plugin.json in the root (or pre-compiled outputs). Administrators can install it dynamically by entering the Git clone URL inside the Clone Git Repository card.