Skip to main content

Getting Started

This section covers everything you need to set up your development environment and create your first widget from the template.

Table of Contents​

  1. Prerequisites and Setup
  2. Creating the Widget Repository
  3. Understanding Project Structure

Prerequisites and Setup​

Reference: Pre-requisites

Before starting widget development, complete the following setup steps:

Required Setup​

  1. Development Credentials

    • GitLab access with appropriate permissions
    • NPM token for private package registry
    • Portal access credentials

  2. Software Installation

    • VS Code or preferred IDE
    • Git version control
    • Node.js (v16 or higher)

  3. Configuration

    • Configure NPM registry authentication
    • Set up SSH keys for GitLab
    • Configure Prettier for code formatting

For detailed setup instructions, follow the complete Prerequisites Guide.

Creating the Widget Repository​

Reference: From Template Tutorial

Create your widget repository using the provided template:

Steps Overview​

  1. Create Repository from Template

    • Follow naming convention: widgets-{vendor-name}-{widget-name}
    • Example: widgets-acme-kpi-tracker
    • See Creating Repository

  2. Clone Repository Locally

  3. Run Setup Wizard

    • Execute npm run setup
    • Configure widget type (Platform: 0, Dashboard: 1, Universal: 2)
    • Provide widget name, vendor prefix, and project ID
    • See Setup Wizard

For complete step-by-step instructions, refer to the From Template Tutorial.

Understanding Project Structure​

Reference: Structure Widget Template Repository

Repository Structure​

widgets-acme-kpi-tracker/
├── .husky/                    # Pre-commit hooks
├── .vscode/                   # VS Code configuration
├── public/                    # Static assets
│   └── preview.svg           # Widget preview image (88x64px)
├── src/
│   ├── widget/               # Main widget implementation
│   │   ├── widget.tsx        # Main widget component
│   │   └── widget-settings.tsx  # Widget settings component
│   ├── widget-preview/       # Widget preview for composer
│   │   └── widget-preview.tsx
│   ├── types/                # TypeScript type definitions
│   ├── hooks/                # Custom React hooks
│   ├── utils/                # Utility functions
│   ├── constants/            # Constants and configuration
│   ├── main.tsx              # Dev mode entry point
│   └── local-widget.tsx        # Dev mode mock data
├── webpack/                  # Webpack configuration
│   ├── webpack.common.js
│   ├── webpack.dev.js
│   ├── webpack.prod.js
│   └── webpack.config.js
├── widget-config.json        # Widget configuration
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── .gitlab-ci.yml            # CI/CD pipeline
├── .eslintrc.js              # ESLint configuration
├── .prettierrc               # Prettier configuration
└── README.md                 # Project documentation

Key Files​

widget-config.json​

Main widget configuration file containing:

  • Widget metadata (ID, port, name, vendor)
  • Widget type and placement rules
  • Module federation exposes
  • Settings schema
  • Layout constraints
  • Note: This file is preconfigured during the setup wizard step (see Creating the Widget Repository)

src/widget/widget.tsx​

Main widget component that:

  • Receives platform props
  • Implements widget logic
  • Renders widget UI

src/widget/widget-settings.tsx​

Settings component that:

  • Provides widget configuration interface
  • Receives settingsSchema from widget-config.json

src/widget-preview/widget-preview.tsx​

Preview component that:

  • Shows widget preview in Dashboard Composer (Host application)
  • Can be static or have simple interactive preview

Next Steps​

Now that you have your project set up and understand the structure, you're ready to:

  1. Dashboard Integration - Learn how widgets integrate with the platform
  2. Configuration - Configure your widget's metadata and settings
  3. Core Features - Implement essential widget functionality

Continue to: Dashboard Integration →