Getting Started with Unisphere Project

This is a temporary documentation to the @unisphere/nx plugin until the official documentation is available.

⚠️ This generator is currently available only to Kaltura developers. It depends on internal resources such as CI/CD templates, design systems, and private NPM packages. External support for Kaltura customers is on our roadmap.

Unisphere is Kaltura’s frontend framework for building dynamic, composable experiences. A Unisphere project is a structured repository that allows developers to create and organize applications, runtimes, and packages under a single cohesive experience. This setup encourages healthy module separation, runtime decoupling, reusability, and clean ownership boundaries — all key ingredients for scaling product development in a multi-team environment.

Whether you're building a full application like Content Lab or a lightweight widget like Chat, Unisphere gives you the tooling and conventions to do it the right way from the start.

Step 1 - Create a New Unisphere Project

Before creating a new Unisphere project, make sure you have a valid GITHUB_TOKEN exported in your environment. This is required for GitHub operations during setup.

To scaffold a new project you can use create-unisphere-project npm package with all necessary tooling and structure, run:

npm create unisphere-project@latest

Set Up the GitHub Repository

Once the project is generated locally, you’ll need to create a new GitHub repository so that CI/CD can operate correctly and your team has proper access.

Please contact Eran Sakal or Omri Ceisler to provision the repository. The following steps will be completed as part of this process:

1. Repository Creation The new repo will be created with internal scope and named according to this convention:

   unisphere-{friendly-experience-name}

   The friendly name is derived from your declared experience name (e.g., unisphere.widget.reactions → reactions → unisphere-reactions as the repository name).

2. Team Access Configuration The appropriate GitHub teams will be granted access to the repository to match the experience's ownership and collaboration needs.

3. CI/CD Enablement These steps are required to ensure that CI/CD workflows are automatically triggered for builds, deployments, versioning, and testing.

Once created, you can push your local project into the new repository and begin active development.

Step 2 - Use the @unisphere/nx Plugin

After your project is set up, you’ll use the @unisphere/nx plugin to generate and manage your project’s core elements. All generators are interactive and designed to enforce Unisphere best practices and conventions.

All generators support interactive usage through nx g and prompt you for the correct configuration.

🧹 add-runtime

Creates a new runtime, one of the possible entry points into an experience. Runtimes define where and how a specific part of the experience is used.

For example, in the Genie experience, there's a runtime called page used when the host injects the experience into the main body of a site, and another called player-plugin for injecting it into a player drawer. We have additional runtimes, one for each tool that is used by the experience, e.g flashcards-tool, source-tool, follow-up-tool etc.

Naming your runtime based on its integration point helps communicate its purpose and role clearly.

npx nx g @unisphere/nx:add-runtime

Prompts

• Runtime name – e.g., page, player-plugin, flashcards-tool, source-tool, follow-up-tool, content-lab-drawer.

• How will this runtime be used?

  • Loaded by External Hostu

    • Deployed independently and loaded at runtime

  • Embedded in Widget Playground

    • Composed by other runtimes, no standalone deployment

• How will this runtime be used?

  • Independent experience used as an entry point (loaded by host or another experience)

    • Includes an Dev playground application for developing and simulating a host environment

  • Composed into another runtime of this experience (not used as an entry point)

    • Composed by another runtime within the same experience

    • Assume it is developed using a playground dev application of another runtime in the project

🎨 add-visual

Creates a visual component within a runtime — the building blocks of your UI.

npx nx g @unisphere/nx:add-visual

Prompts

• Runtime name – Where this visual belongs
• Visual name – e.g., card, toolbar, timeline-visual
• Is this visual limited to a single occurrence? Choose Yes for singleton visuals (e.g., when the visual represent a container that can only have one instance), otherwise No.

📱 add-application

Creates an application that acts as a host for your runtime(s). These apps can be used for development, standalone deployments, or iframe integrations. The application can be used as a playground for developing and simulating a host environment without the need to deploy the experience to a customer, or it can be an additional entry point for the experience and use the Unisphere ci/cd to be publically available in multi region environments.

npx nx g @unisphere/nx:add-application

Prompts

• Application name

• Serving type

  • Local Dev Playground – Local development playground (for development and testing)
  • Self-Hosted – Standalone deployment with routing/auth (used for publically available applications)
  • Iframe + Query Params – Embedded apps with config in URL (used for embedding into other applications like Kaltura Admin or KMC)
  • Iframe + Post Messages – Embedded apps using postMessage API (used for embedding into other applications like Kaltura Admin or KMC) - this will replace eventually the query param method to be more secure and reliable but is not yet available.

• Runtime to load in playground (if Playground selected)

• HTML page title (if not using Playground)

📦 add-package

Creates a shared package for separating concerns within an experience. Most of the actual code in a Unisphere project lives in packages — not in runtimes — making it easier to reuse components, services, and logic across multiple entry points. These packages are usually not distributed externally but serve as internal modules consumed by runtimes.

By using packages this way, you can introduce multiple runtimes (e.g., page, player-plugin, admin-panel) that share the same functionality while remaining decoupled.

Some packages, however, are designed for external consumption. For example:

• Each experience has a Core package expose the types needed for runtime integration.
• Differetn kit packages act as extendable, design-system-driven building blocks that allow other teams to plug into your experience in a consistent and styled way.

Packages can be published to GitHub or npm, but in most cases, they serve as a clean internal abstraction layer inside the experience repository without being deployed.

npx nx g @unisphere/nx:add-package

Prompts

• Package name

• Package scope

  • None (no scope) - Used only internally by the experience runtimes.
  • Internal - Published to GitHub packages (@kaltura/unisphere-<experience-name>-<package-name>)
  • Public - Published to npm (@unisphere/<experience-name>-<package-name>)

Best Practices

🧠 Use descriptive names that reflect the purpose of the runtime or visual. For example, use player-plugin for a runtime that integrates into a video player, or container for visual that represent a container that can only have one instance, or drawer if it is a drawer runtime.

🎯 Select the correct runtime type depending on the deployment context. Choose "Independent experience" if the runtime will be loaded by a host or standalone app, and "Composed into another runtime" if it will only exist as part of a larger experience.

♻️ Share logic and components using packages. Most Unisphere code lives in packages rather than runtimes. This promotes reusability and modularity — for instance, content-lab-drawer and content-lab-modal runtimes may reuse the same internal package. Use the non scoped package if you are not sure what to choose.

🔍 Use the interactive CLI mode to generate all project elements. This ensures naming consistency, correct scaffolding, and alignment with Unisphere conventions.

What’s Next?

Stay tuned for full documentation on each concept and tool at unisphere.kaltura.com (coming soon)