Skip to main content

Creating a Widget Tutorial

Complete Tutorial: Building a KPI Tracker Widget

This comprehensive tutorial guides you through creating a fully-featured KPI Tracker widget that demonstrates all available platform APIs and features. The widget will:

  • Display real-time key performance indicators
  • Connect to third-party APIs with OAuth authentication
  • Share state with other widgets
  • Use theming and UI-Kit components
  • Handle WebSocket updates
  • Support feature flags
  • Include comprehensive settings
  • Be accessible and well-tested

Tutorial Structure​

This tutorial is organized into logical sections that build upon each other:

1. Getting Started​

Set up your development environment and create your first widget from the template. Covers:

  • Prerequisites and required setup
  • Creating the widget repository from template
  • Understanding the project structure
  • Key files and directories

2. Development Workflow​

Set up your local development environment and connect to the portal. Covers:

  • Local development with dev mode
  • Widget version control
  • Connecting local widget to portal for debugging
  • Development best practices

3. Deployment​

Release your widget to production. Covers:

  • Semantic versioning and commit conventions
  • Creating merge requests
  • CI/CD pipeline and deployment
  • Version management in portals

4. Dashboard Integration​

Learn how widgets integrate with the platform's Dashboard Composer. Covers:

  • Dashboard Composer and Micro App Library
  • Widget presets (Derived Micro Apps)
  • Building the main widget component
  • Widget props and interfaces

5. Configuration​

Configure your widget's metadata, appearance, and settings. Covers:

  • Configuring widget metadata
  • Using theming and styling with UI-Kit
  • Creating widget settings with JSON Schema
  • Implementing widget preview

6. Layout Testing​

Make your widget responsive and well-tested. Covers:

  • Layout and responsive design
  • Component testing with React Testing Library
  • Accessibility testing with jest-axe
  • Code style and linting

7. Core Features​

Implement essential widget functionality and platform integrations. Covers:

  • API integration with httpClient
  • Adding notifications
  • React Query integration
  • Dashboard navigation and platform meta

8. Advanced Features​

Implement advanced platform features. Covers:

  • OAuth authentication with ProxyApp
  • State sharing between widgets
  • WebSocket updates with BFF-WS-EXT
  • Feature flags
  • Remote modules
  • Working with extensions

Learning Path​

For Beginners​

If you're new to the platform, we recommend following the tutorial in order:

  1. Start with Getting Started - Set up your environment
  2. Learn Development Workflow - Test locally
  3. Understand Deployment - Release to production
  4. Move to Dashboard Integration - Build your first widget
  5. Then Configuration - Make it configurable
  6. Add Layout Testing - Make it responsive and tested
  7. Next Core Features - Add platform features
  8. Finally Advanced Features - Implement advanced functionality

For Experienced Developers​

If you're familiar with React and microfrontend architecture, you can:

  • Quick start: Follow sections 1-2 to get up and running quickly
  • Reference sections: Jump to specific sections as needed (Configuration, Layout Testing, Core Features, Advanced Features)
  • Deep dive: Focus on platform-specific features in sections 7 and 8

Prerequisites​

Before starting this tutorial, ensure you have:

  • ✅ GitLab access with appropriate permissions
  • ✅ NPM token for private package registry
  • ✅ Portal access credentials
  • ✅ VS Code or preferred IDE installed
  • ✅ Git version control installed
  • ✅ Node.js v16 or higher installed

See the Getting Started section for detailed setup instructions.

What You'll Build​

By the end of this tutorial, you'll have built a complete KPI Tracker widget featuring:

  • Real-time Data Display: Shows key performance indicators (revenue, users, conversion)
  • OAuth Integration: Connects to third-party APIs securely
  • State Sharing: Shares data with other widgets on the dashboard
  • WebSocket Updates: Receives real-time updates without polling
  • Theming: Uses the platform's theming system for consistent UI
  • Settings: Comprehensive configuration through JSON Schema forms
  • Feature Flags: Conditional features based on portal configuration
  • Accessibility: WCAG-compliant with proper ARIA attributes
  • Responsive: Adapts to different screen sizes and grid layouts
  • Well-tested: Unit tests and accessibility tests

Additional Resources​

Getting Help​

If you encounter issues or have questions:

  • Check the relevant section of this tutorial
  • Review the Widget Guidelines
  • Consult your INVENT technical manager
  • Review the example widgets in the platform

Ready to get started? Head to Getting Started →