Plugin SystemMigration Guide

Migration Guide: Custom Nodes to Plugins

This guide explains how to migrate existing custom nodes to the new plugin system using NetPad’s modern node architecture.

Why Migrate?

  • Unlock plugin store distribution and management
  • Gain access to audit logging, security, and compliance features
  • Use modern node visuals and configuration

Key Migration Steps

  1. Extract Node Logic
    • Move your node’s logic into a runner.js file
  2. Create a Plugin Manifest
    • Define your plugin’s metadata, permissions, and visuals in manifest.json
  3. Refactor Node Shape
    • Use ModernNodeBase and config from the manifest
  4. Test with PluginDevServer
    • Use hot-reload and the test framework to validate your plugin
  5. Publish and Install
    • Use the CLI to publish and install your new plugin

Before & After Example

Before: Custom Node

export default function CustomNodeShape({ shape, isSelected }) {
  // 200+ lines of custom styling...
}

After: Plugin Node

import { getPluginConfig } from '...';
import ModernNodeBase from '...';
export default function CustomNodeShape({ shape, isSelected }) {
  const config = getPluginConfig('custom_node');
  return (
    <ModernNodeBase shape={shape} isSelected={isSelected} config={config}>
      <APIVisualization x={shape.x} y={shape.y} width={shape.width} />
    </ModernNodeBase>
  );
}

Best Practices

  • Use the manifest for all config and permissions
  • Leverage existing NodeVisualizations for visuals
  • Keep runner logic modular and testable
  • Document migration steps in your plugin’s README

Further Reading

For more, see the Plugin Sprint Plan.

ExamplesArchitecture