Pilet Management

The Pilet Management page allows you to upload, manage, and configure microfrontend modules (pilets) for your projects.

Overview

Pilets are packaged microfrontend modules that can be dynamically loaded by frontend applications. The Manager UI provides a comprehensive interface for:

• Upload: Add new pilet packages to your project
• Version Control: Manage multiple versions of each pilet
• Enable/Disable: Control which pilets are active
• Download: Retrieve pilet packages for backup or deployment
• Edit Metadata: Update descriptions and configuration

Accessing Pilets

Navigate to Pilets from the main navigation menu. The page displays all pilets associated with the currently selected project.

Pilet List View

The main table displays all pilets with the following information:

Column	Description
Name / Version	Pilet package name and semantic version (e.g., @myapp/dashboard v1.0.0)
Description	Optional description of the pilet's functionality
Size	Package size in human-readable format (KB, MB)
Hash	SHA256 hash (truncated, hover for full hash)
Status	Badge showing if the pilet is Enabled or Disabled
Created	When the pilet was uploaded
Actions	Quick action buttons (Download, Enable/Disable, Edit)

Filtering

Use the filter controls to narrow down the pilet list:

• Filter dropdown: Show All, Enabled Only, or Disabled Only pilets
• Search box: Search by name, version, or description

Uploading Pilets

To upload a new pilet or update an existing one:

1. Click the Upload Pilet button in the top right

2. Fill in the upload form:

   • Package Name: The pilet's name (supports scoped packages like @myapp/dashboard)
   • Version: Semantic version (e.g., 1.0.0, 2.1.3)
   • Description (optional): Brief description of the pilet
   • Package File: Select the .tgz or .tar.gz file (max 50MB)

3. Click Upload to submit

Automatic Settings Update

When you upload a pilet, it's automatically added to AvailableModules in all frontend settings connected to the project (project, tenant, and application levels). You no longer need to manually update settings to make the pilet available.

Name Format

Pilet names support:

• Alphanumeric characters
• Dashes, underscores, dots
• Scoped packages: @scope/name

Examples: dashboard, @myapp/analytics, reporting-module

File Size Limit

The maximum package size is 50MB. Larger packages will be rejected.

Upload Validation

The form validates:

• Name: Must be a valid package name
• Version: Must follow semantic versioning format
• File: Must be .tgz or .tar.gz format and under 50MB

Managing Pilets

Editing Descriptions

To update a pilet's description:

1. Click the Edit button (pencil icon) in the Actions column
2. Modify the description in the dialog
3. Click Save

INFO

Only the description can be edited. To update the package content or version, upload a new version.

Enabling/Disabling Pilets

Control which pilets are active:

• Enable: Click the checkmark icon on disabled pilets
• Disable: Click the ban icon on enabled pilets

Disabled pilets remain in the system but won't be loaded by applications.

Soft Deletes with Auto-Cleanup

When you disable (delete) a pilet:

• The pilet is soft-deleted (remains in the system for audit purposes)
• It's automatically removed from both AvailableModules and EnabledModules in all frontend settings
• This applies to project, tenant, and application level settings
• Applications will immediately stop loading the pilet on their next configuration fetch

Downloading Pilets

To download a pilet package:

1. Click the Download button (download icon)
2. The browser will download the .tgz file

Downloaded files are named: {name}-{version}.tgz

This is useful for:

• Backing up pilet packages
• Deploying to other environments
• Local development and testing

Integration with Frontend Configuration

Pilets are loaded by frontend applications based on the Frontend Settings configuration.

Available Modules

The AvailableModules array lists all pilets that can be enabled. This is automatically managed by the system:

• When you upload a pilet: Added to AvailableModules as {name}@{version}
• When you update a pilet: Version is updated in AvailableModules
• When you delete a pilet: Removed from AvailableModules

The automatic updates apply to:

• Project-level settings
• Tenant-level settings (for all tenants in the project)
• Application-level settings (for all applications in the project's tenants)

Enabled Modules

In the Frontend Settings editor, the EnabledModules array specifies which pilets should be loaded:

{
  "module_config": {
    "available_modules": [
      "@myapp/dashboard@1.0.0",
      "@myapp/analytics@2.1.0",
      "@myapp/settings@1.0.0"
    ],
    "enabled_modules": ["@myapp/dashboard@1.0.0", "@myapp/analytics@2.1.0"]
  }
}

You need to manually add pilets to EnabledModules to make them load in your application. The pilet must exist in AvailableModules first (which happens automatically on upload).

Version Specification

You can specify versions in different ways:

• Specific version: @myapp/dashboard@1.0.0 - Load exact version
• Without version: @myapp/dashboard - Load latest enabled version
• Version range: @myapp/dashboard@^1.0.0 - Load compatible versions (resolved by frontend)

Security and Access Control

Authentication

All pilet operations require authentication:

• Web UI: Session-based authentication (automatic when logged in)
• API: Personal Access Token (PAT) or Bearer token

Authorization

• You must have access to the project to manage its pilets
• Creator and editor information is tracked for audit purposes

Hash Verification

Each pilet has a SHA256 hash that can be used to verify integrity:

1. Download the pilet
2. Calculate SHA256 locally: sha256sum downloaded-file.tgz
3. Compare with the hash shown in the UI (click hash chip to see full value)

Best Practices

Versioning

• Use semantic versioning (major.minor.patch)
• Increment versions appropriately:
  • Major: Breaking changes
  • Minor: New features, backward compatible
  • Patch: Bug fixes

Descriptions

Write clear, concise descriptions:

• [OK] "User dashboard with analytics widgets"
• [OK] "Reporting module with PDF export"
• [NO] "Module" (too vague)

Package Management

• Test locally before uploading
• Keep packages small - remove unnecessary files before packing
• Version consistently - match your git tags or release versions
• Disable unused versions instead of trying to delete them

Configuration

• List only enabled pilets in EnabledModules
• Specify exact versions for production deployments
• Use version ranges for development/testing environments

Troubleshooting

Upload Fails

Problem: Upload button doesn't work or shows error

Solutions:

• Check file size (must be < 50MB)
• Verify file format (must be .tgz or .tar.gz)
• Ensure package name is valid
• Confirm version follows semantic versioning

Pilet Not Loading in Application

Problem: Pilet is enabled but doesn't appear in the app

Solutions:

1. Check if the pilet is listed in EnabledModules in Frontend Settings
2. Verify the version matches (or remove version to get latest)
3. Ensure the pilet is enabled (green badge)
4. Check browser console for loading errors
5. Verify authentication tokens are valid

Hash Mismatch

Problem: Downloaded pilet has different hash

Solutions:

• Re-download the pilet
• Check network connection stability
• Verify no proxy is modifying content
• Contact support if issue persists

Related Documentation

• Pilet API Reference - Technical API documentation
• Frontend Settings - Configure enabled modules
• Authentication - Access control details
• GraphQL API - Programmatic access

Examples

Complete Workflow

1. Build your pilet:

   cd my-pilet
   pnpm build
   pnpm pack

2. Upload via UI:

   • Open Pilets page
   • Click "Upload Pilet"
   • Name: @myapp/dashboard
   • Version: 1.0.0
   • Select the generated .tgz file
   • Click Upload

3. Enable in Frontend Settings:

   • Navigate to Settings page
   • Edit Frontend Settings
   • The pilet is already in AvailableModules (automatically added on upload)
   • Add to EnabledModules:

     ["@myapp/dashboard@1.0.0"]

   • Or select it in the GUI editor

4. Application loads pilet:

   • Frontend fetches config
   • Downloads pilet package
   • Dynamically loads module

CI/CD Integration

For automated uploads, use the REST API:

#!/bin/bash
PROJECT_ID="your-project-id"
PAT_TOKEN="your-pat-token"

curl -X POST \
  -H "Authorization: Bearer $PAT_TOKEN" \
  -H "Content-Type: application/gzip" \
  --data-binary @my-pilet-1.0.0.tgz \
  "https://manager.example.com/pilets/$PROJECT_ID/@myapp/dashboard/1.0.0"

See Pilet API Reference for more details.