Skip to content

Add New Module

Jump to bottom
Sharjeel Yunus edited this page Mar 8, 2026 · 2 revisions

Adding a New Module in Ensemble

This guide describes the complete workflow for adding a new module to Ensemble and ensuring it works across the entire platform.

Because Ensemble spans multiple repositories, adding a module requires coordinated updates across runtime, Studio, documentation, and preview validation.

Overview

A module integration touches several components of the Ensemble platform:

Component Purpose
Ensemble Runtime Implements the module functionality
Starter Scripts Ensures new apps include required setup
Documentation Provides user documentation
Studio Build System Allows user to build and deploy the app from studio
Ensemble Live Ensemble Go (ios), Ensemble Preview (Android) and Studio Preview
Studio Schema Enables IntelliSense and validation
KitchenSink Provides working examples

Module Integration Flow

Runtime Implementation
        ↓
Starter Scripts
        ↓
Documentation
        ↓
Studio Service / Build Updates
        ↓
Ensemble Live Integration
        ↓
Run Studio Preview Deploy
        ↓
Validate Studio Preview
        ↓
Update Studio Schema
        ↓
Add KitchenSink Example
        ↓
Merge Preview PR

Step‑by‑Step Guide

1. Add the Module to the Ensemble Runtime

Implement the new module inside the Ensemble runtime.

Typical tasks include:

  • Creating the module implementation
  • Registering the module
  • Adding dependencies
  • Exposing required APIs

Follow the structure used by existing modules when possible.

Example modules:

  • Camera
  • Bluetooth
  • Location

2. Update Starter Scripts

Update the starter scripts so new apps can support the module.

Location

starter/scripts

These scripts ensure that newly created starter apps include the correct module setup.

3. Update Documentation

Add documentation for the new module.

Repository:

https://github.com/EnsembleUI/ensemble_docs

Documentation should include:

  • Module overview
  • Configuration
  • Required permissions
  • Usage examples
  • Supported actions and widgets

4. Update the Studio Build System

Update the Studio build system to support the module.

Repository:

https://github.com/EnsembleUI/studio_service

Steps:

  1. Locate scripts related to module builds.
  2. Follow the structure used by existing modules.
  3. Add support for the new module.

5. Integrate the Module in Ensemble Live

Before running the Studio preview deployment, integrate the module into:

https://github.com/EnsembleUI/ensemble_live

Why this is required

The Studio preview deployment workflow depends on ensemble_live.
If the module is not integrated here, the preview deploy will not include the new module.

6. Run Studio Preview Deploy

Run the GitHub Action:

Studio Preview Deploy

Workflow:

https://github.com/EnsembleUI/ensemble_live/actions/workflows/studio-preview-deploy.yml

This action will automatically create a Pull Request in:

https://github.com/EnsembleUI/ensemble-web-studio/pulls

PR name:

[AUTO] Preview build

7. Validate the Studio Preview

Open the preview link provided in the generated PR and perform validation.

Test the following:

  • Opening an existing app
  • Running screens
  • Editing YAML
  • Saving and updating code
  • Using the new module

Ensure:

  • The new module works correctly
  • No existing functionality is broken

8. Update the Studio Schema

Update schema definitions used by Studio.

Repository:

https://github.com/EnsembleUI/ensemble-web-studio

Path:

src/schema

Schema definitions enable:

  • IntelliSense
  • Autocomplete
  • YAML validation

Make sure module properties and actions are properly defined.

9. Add a KitchenSink Example

Add a KitchenSink example demonstrating the new module.

This provides:

  • A working reference for developers
  • A validation case for Studio

10. Merge the Preview PR

Once validation is complete:

  1. Confirm Studio preview works correctly.
  2. Confirm KitchenSink example works.
  3. Confirm schema behavior works.

Then merge the PR:

[AUTO] Preview build

Developer Checklist

Runtime

  • Module implemented in Ensemble runtime
  • Module registered correctly
  • Dependencies added

Project Setup

  • Starter scripts updated

Documentation

  • Documentation added in ensemble_docs
  • Usage examples included

Studio

  • Studio build scripts updated in studio_service
  • Schema updated in ensemble-web-studio/src/schema

Deployment

  • Changes integrated in ensemble_live
  • Studio Preview Deploy executed

Validation

  • Studio preview tested
  • KitchenSink example added
  • Existing Studio functionality verified

Important Notes

A module is considered complete only when:

  • Studio supports the module
  • Schema works correctly
  • KitchenSink example runs successfully
  • Existing Studio functionality remains stable

Clone this wiki locally