A sample Power Platform Tool Box tool built with React
npm install pptb-react-sample-toolA complete example tool for Power Platform Tool Box built with React 18, Vite, and TypeScript.
This sample demonstrates:
- ✅ React 18 with hooks and functional components
- ✅ TypeScript with full type safety
- ✅ Vite for fast development and optimized builds
- ✅ ToolBox API Integration
- Connection management with real-time updates
- Notifications system
- Clipboard operations
- File save dialogs
- Theme detection
- Event subscription and handling
- ✅ Dataverse API Usage
- FetchXML queries
- CRUD operations (Create, Read, Update, Delete)
- Entity metadata retrieval
- Error handling
- ✅ Best Practices
- Custom React hooks for API integration
- Component-based architecture
- Proper state management
- Event-driven architecture
- Clean, modern UI design
- Responsive layout
- Node.js 18 or higher
- Power Platform Tool Box desktop application
``bash`
npm install
`bash`
npm run build
This compiles the TypeScript and React code, and outputs to the dist/ directory.
For local development with hot module replacement:
`bash`
npm run dev
Note: The dev server will run, but ToolBox APIs will only be available when loaded within Power Platform Tool Box.
``
react-sample/
├── src/
│ ├── components/
│ │ ├── ConnectionStatus.tsx # Connection display component
│ │ ├── ToolboxAPIDemo.tsx # ToolBox API examples
│ │ ├── DataverseAPIDemo.tsx # Dataverse API examples
│ │ └── EventLog.tsx # Event logging component
│ ├── hooks/
│ │ └── useToolboxAPI.ts # Custom hooks for APIs
│ ├── App.tsx # Main app component
│ ├── main.tsx # React entry point
│ ├── index.css # Global styles
│ └── vite-env.d.ts # Type definitions
├── index.html # HTML entry point
├── vite.config.ts # Vite configuration
├── tsconfig.json # TypeScript configuration
├── tsconfig.node.json # Node TypeScript configuration
├── package.json # Package configuration
└── README.md # This file
The sample includes reusable hooks for API integration:
#### useConnection()`typescript`
const { connection, isLoading, refreshConnection } = useConnection();
- Manages Dataverse connection state
- Automatically loads on mount
- Provides refresh function
#### useToolboxEvents(onEvent)`typescript`
useToolboxEvents((event, data) => {
console.log('Event:', event, data);
});
- Subscribes to platform events
- Automatic cleanup on unmount
#### useEventLog()`typescript`
const { logs, addLog, clearLogs } = useEventLog();
- Manages event log state
- Keeps last 50 entries
- Console integration
Each component is self-contained and demonstrates specific functionality:
- ConnectionStatus: Displays current Dataverse connection
- ToolboxAPIDemo: Demonstrates ToolBox API features
- DataverseAPIDemo: Demonstrates Dataverse CRUD and queries
- EventLog: Real-time event logging with filtering
1. Open Power Platform Tool Box
2. Go to Tools section
3. Click "Install Tool"
4. Enter the path to this directory or publish to npm and use the package name
#### Connection Status
- Real-time connection information
- Environment type badges
- Automatic updates on connection changes
#### ToolBox API Examples
Notifications:
`typescript`
await window.toolboxAPI.utils.showNotification({
title: 'Success',
body: 'Operation completed',
type: 'success',
duration: 3000
});
Utilities:
- Copy data to clipboard
- Get current theme (light/dark)
- Save data to file with native dialog
#### Dataverse API Examples
Query with FetchXML:
`typescript`
const result = await window.dataverseAPI.fetchXmlQuery(fetchXml);
CRUD Operations:
`typescript
// Create
const account = await window.dataverseAPI.create('account', { name: 'Test' });
// Update
await window.dataverseAPI.update('account', id, { telephone1: '555-0100' });
// Delete
await window.dataverseAPI.delete('account', id);
`
Metadata:
`typescript`
const metadata = await window.dataverseAPI.getEntityMetadata('account');
1. Create component in src/components/App.tsx
2. Import and use in
3. Use custom hooks for API access
1. Create hook in src/hooks/use[Feature].ts
2. Follow naming convention:
3. Export from hook file
This tool uses TypeScript with the @pptb/types package:
`typescript
///
// Full type safety for APIs
const toolbox = window.toolboxAPI;
const dataverse = window.dataverseAPI;
`
Global styles are in src/index.css. Components use CSS classes for styling.
To modify styles:
1. Edit src/index.css
2. Changes apply immediately in dev mode
3. Rebuild for production
`bash`
npm run build
Output goes to dist/ directory with:
- Optimized and minified JavaScript
- CSS extraction and minification
- Asset optimization
- Source maps for debugging
If you encounter TypeScript errors:
1. Ensure all dependencies are installed: npm installtsc --version
2. Check TypeScript version: rm -rf dist && npm run build
3. Clean and rebuild:
If you see "Rules of Hooks" warnings:
- Ensure hooks are only called at the top level
- Don't call hooks inside loops, conditions, or nested functions
- Only call hooks from React components or custom hooks
If toolboxAPI or dataverseAPI is undefined:
- The tool must be loaded within Power Platform Tool Box
- These APIs are injected by the platform
- They are not available in standalone dev mode
If connection is null:
- Open Power Platform Tool Box
- Create a connection to a Dataverse environment
- The tool will automatically detect the connection via events
The vite.config.ts is configured for Power Platform Tool Box compatibility:
`typescript`
export default defineConfig({
plugins: [react(), fixHtmlForPPTB()],
base: './', // Relative paths for embedded usage
build: {
outDir: 'dist',
assetsDir: 'assets',
rollupOptions: {
output: {
// Use IIFE format for compatibility with iframe + file:// URLs
format: 'iife',
// Bundle everything into a single file
inlineDynamicImports: true,
manualChunks: undefined,
},
},
}
});
Key Configurations for PPTB:
- IIFE Format: Uses Immediately Invoked Function Expression instead of ES modules for compatibility with PPTB's iframe loading mechanism
- Single Bundle: All code and CSS bundled into one file to avoid module loading issues
- HTML Plugin: Custom plugin that:
- Removes type="module" and crossorigin attributes for proper loading with file:// URLs
- Moves script tags from
to end of ` so DOM elements are available when IIFE executes- React Documentation
- Vite Documentation
- TypeScript Documentation
- Tool Development Guide
- API Reference
- Power Platform Tool Box Repository
GPL-3.0 - See LICENSE file in repository root