Skip to main content

Quick Reference

Screen Placement Options​

Dashboard Plugin​

{
  "cncPlugin": {
    "ui": {
      "placement": "dashboard",
      "screen": "main",
      "size": { "width": 400, "height": 300 },
      "priority": 100
    }
  }
}
  • Use for: Status cards, quick controls, monitoring widgets
  • Size: 200-800px width, 150-600px height
  • Grid: Responsive grid layout

Standalone Plugin​

{
  "cncPlugin": {
    "ui": {
      "placement": "standalone",
      "screen": "new",
      "menuTitle": "My Tool",
      "menuIcon": "ToolOutlined",
      "routePath": "/my-tool"
    }
  }
}
  • Use for: Full applications, file managers, configuration tools
  • Navigation: Adds menu item to sidebar
  • Routing: Custom URL path
{
  "cncPlugin": {
    "ui": {
      "placement": "modal",
      "size": { "width": 600, "height": "auto" }
    }
  }
}
  • Use for: Settings dialogs, confirmations, forms
  • Trigger: Activated by user action or other plugins
  • Size: Auto-sizing or fixed dimensions
{
  "cncPlugin": {
    "ui": {
      "placement": "sidebar",
      "size": { "width": 300, "height": "auto" }
    }
  }
}
  • Use for: Tool palettes, quick settings, shortcuts
  • Collapsible: Can be minimized by user
  • Position: Left or right side of screen

Available Screens​

ScreenPurposePlugin Types
mainMain dashboardDashboard, Modal
controlsJog controlsDashboard, Sidebar
machineMachine statusDashboard, Modal
workspaceFile managementDashboard, Standalone
settingsApplication settingsModal, Standalone
newDedicated screenStandalone only

Permissions Reference​

PermissionAccess LevelUse Cases
machine.readRead machine status, positionStatus displays, monitoring
machine.writeSend G-code commandsControl panels, automation
machine.controlFull machine controlAdvanced control interfaces
status.readSystem status informationHealth monitoring, diagnostics
files.readRead G-code filesFile viewers, analyzers
files.writeCreate/modify filesFile editors, generators
config.readApplication configurationSettings displays
config.writeModify configurationSettings editors
network.accessExternal API callsCloud sync, remote monitoring

Publishing Checklist​

Pre-Publishing​

  • Plugin builds without errors
  • All tests pass
  • Manifest is valid JSON
  • Required fields completed
  • Permissions documented
  • Version follows semver

GitHub Release​

  • Tag format: {plugin-id}-v{version}
  • ZIP file attached as asset
  • Release notes included
  • Changelog updated

Registry Submission​

  • Fork plugin-registry repo
  • Add plugins/{plugin-id}/plugin.json
  • Submit pull request
  • Wait for approval
  • Create GitHub release

Common Configuration Patterns​

Basic Dashboard Widget​

const MyWidget: React.FC<PluginProps> = ({ api }) => {
  const jogSpeed = api.config.get('jog.speed.xy');
  const units = api.config.get('machine.units');
  
  return (
    <div className="plugin-card">
      <h4>Jog Speed</h4>
      <p>{jogSpeed} {units}/min</p>
    </div>
  );
};

Configuration Section Access​

// Get entire configuration sections
const machineConfig = api.config.getSection('machine');
const jogSettings = api.config.getSection('jog');
const uiSettings = api.config.getSection('ui');

// Access nested values
const homeX = api.config.get('machine.home.x');
const theme = api.config.get('ui.theme');

Error Handling​

const MyPlugin: React.FC<PluginProps> = ({ api }) => {
  const [error, setError] = useState<string | null>(null);
  
  const safeConfigGet = (path: string, fallback: any) => {
    try {
      return api.config.getWithFallback(path, fallback);
    } catch (err) {
      setError(`Configuration error: ${err.message}`);
      return fallback;
    }
  };
  
  if (error) {
    return <div className="plugin-error">{error}</div>;
  }
  
  // Normal plugin render
};

Plugin Categories​

CategoryDescriptionExamples
monitoringStatus and diagnosticsMachine monitor, connection status
controlMachine operationJog controls, spindle control
visualization3D/2D displaysG-code viewer, toolpath preview
utilityHelper toolsCalculator, unit converter
automationAutomated workflowsAuto-leveling, tool changing
managementAsset managementTool library, material database

Size Guidelines​

Dashboard Cards​

  • Small: 400x300px (status displays)
  • Medium: 600x400px (controls, forms)
  • Large: 800x600px (complex widgets)

Standalone Apps​

  • Full screen: Use available space
  • Responsive: Adapt to window size
  • Mobile friendly: Consider tablet use

Modals​

  • Small: 400x300px (confirmations)
  • Medium: 600x400px (forms, settings)
  • Large: 800x600px (complex dialogs)
  • Auto: Let content determine size

Commands Reference​

# Plugin development
npm run create-plugin <name> "<title>" <placement>
npm run dev                    # Start development server
npm run build                  # Build for production
npm run test                   # Run test suite
npm run validate               # Validate plugin manifest

# Registry management
npm run add-plugin <path>      # Add plugin to registry
npm run update-plugin <id>     # Update plugin version
npm run package-plugin <id>    # Create distribution ZIP
npm run validate-registry      # Validate entire registry

Useful Resources​