Skip to main content

Creating Widget from Existing Widget

This guide covers how to fork or adapt an existing widget to create a new one.

Overview​

While creating widgets from the template is the recommended approach, you may sometimes want to create a new widget based on an existing one. This is useful when:

  • You need to create a variant of an existing widget
  • You want to fork a widget for customization
  • You're migrating a widget to a new repository

For most use cases, we recommend using the widget template:

Creating Widget from Template - Complete step-by-step guide

The template provides:

  • Latest platform dependencies
  • Correct configuration structure
  • Pre-configured build system
  • Example code and tests

When to Fork an Existing Widget​

Fork an existing widget when you need to:

  1. Create a Variant

    • Similar functionality with different data source
    • Same UI with different configuration
    • Customized version for specific use case

  2. Vendor Customization

    • Fork a core widget for vendor-specific changes
    • Maintain separate version with custom features

  3. Migration

    • Move widget to new repository
    • Transfer ownership to different team

Forking Process​

1. Fork the Repository​

In GitLab:

  1. Navigate to the source widget repository
  2. Click Fork button
  3. Select your vendor's subgroup (widgets-vendorName)
  4. Update repository name: widgets-vendorName-newWidgetName

2. Update Configuration​

Update the following files with new widget identity:

widget-config.json​

{
  "widgetDetails": {
    "name": "VendorNewWidgetName",
    "id": "new-widget-id",
    "port": 5XXX,  // Use new GitLab Project ID
    "widgetType": 1,
    ...
  }
}

Important: Update name, id, and port to match the new widget.

package.json​

{
  "name": "@invent/widgets-vendor-new-widget-name",
  "scripts": {
    "start_federation": "webpack serve --port 5XXX ..."
  }
}

Update package name and port.

build-vars.js​

PORT: process.env.PORT || 5XXX

Match port to GitLab Project ID.

3. Update Dependencies​

npm install
npm update

Ensure all dependencies are up to date.

4. Clean Git History (Optional)​

If you want a clean git history:

# Remove old git history
rm -rf .git

# Initialize new repository
git init
git add .
git commit -m "feat: initial commit from forked widget"

# Add remote and push
git remote add origin <your-new-repo-url>
git push -u origin master

5. Update Code​

Rename files and update code to reflect new widget name:

# Rename widget files
mv src/widget/old-widget-name.tsx src/widget/new-widget-name.tsx

# Update imports and references
# Search and replace "OldWidgetName" with "NewWidgetName"

6. Test Locally​

npm run dev

Verify the widget runs correctly with new configuration.

7. Create Initial Release​

git add .
git commit -m "feat: initial new widget from fork"
git push

Create merge request with feat: prefix to trigger initial release.

Differences from Template​

When forking an existing widget instead of using the template:

Advantages:

  • Reuse existing functionality
  • Keep UI and logic
  • Faster initial development

Disadvantages:

  • May have outdated dependencies
  • Might include unnecessary code
  • Could have legacy patterns
  • Needs more cleanup work

Best Practice: After forking, review and update:

  • Dependencies to latest versions
  • Code to current patterns
  • Remove unused features
  • Update tests

Alternative: Copy Code from Existing Widget​

Instead of forking, you can:

  1. Create widget from template
  2. Copy relevant code from existing widget
  3. Adapt to new widget's needs

This approach gives you:

  • Latest template structure
  • Clean git history
  • Up-to-date dependencies
  • Only the code you need

Recommended for: New widgets that need some features from existing widgets but aren't direct variants.

Next Steps​

After creating your widget:

  1. Configuration - Configure metadata and settings
  2. Development Workflow - Local development
  3. Deployment - Deploy to platform