@unisphere/nx 1.1.1 → 1.1.3

package/README.md

@@ -1,32 +1,181 @@
-# @unisphere/nx
+# Getting Started with Unisphere Project
 
-This library was generated with [Nx](https://nx.dev).
+> This is a temporary documentation to the @unisphere/nx plugin until the official documentation is available.
 
-## Building
+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.
 
-Run `nx build unisphere-generator` to build the library.
+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.
 
-## Running unit tests
+---
 
-Run `nx test unisphere-generator` to execute the unit tests via [Jest](https://jestjs.io).
+## Create a New Unisphere Project
 
+To scaffold a new project you can use [create-unisphere-project](https://www.npmjs.com/package/create-unisphere-project) npm package with all necessary tooling and structure, run:
 
-## Run Add Package
+```bash
+npm create unisphere-project@latest
+```
 
-Run `npx nx g @unisphere/nx:add-package` to build the library.
+> ⚠️ **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.
 
-## Run Add Runtime
+**Before running the command**, make sure you have a valid `GITHUB_TOKEN` exported in your environment. This is required for GitHub operations during setup.
 
-Run `npx nx g @unisphere/nx:add-runtime` to build the library.
+---
 
-## Run Add Application
+### Set Up the GitHub Repository
 
-Run `npx nx g @unisphere/nx:add-application` to build the library.
+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:
 
-## Run in another folder with path of current plugin
+1. **Repository Creation**
+   The new repo will be created with **internal scope** and named according to this convention:
 
-Run `npx nx g <path-of-current-repo>packages/nx:add-application` to build the library.
+   ```
+   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.
+
+---
+
+## 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.
+
+```bash
+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 Host**
+
+    - 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 Expo playground expo 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 expo application of another runtime in the project
+
+---
+
+### 🎨 `add-visual`
+
+Creates a **visual component** within a runtime — the building blocks of your UI.
+
+```bash
+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.
+
+```bash
+npx nx g @unisphere/nx:add-application
+```
+
+#### Prompts
+
+- **Application name**
+
+- **Serving type**
+
+  - **Interactive Playground** – Local development using Expo (used mostly 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.
+
+```bash
+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](https://unisphere.kaltura.com)** _(coming soon)_

package/dist/generators/add-application/templates/interactive-playground/src/app/app.tsx.template

@@ -10,6 +10,98 @@ import { UnisphereWorkspaceConfig } from '@unisphere/runtime';
 import { UnisphereWorkspaceType } from '@unisphere/runtime';
 import { <%= runtimeName__pascalCase %>Runtime } from '<%= coreAlias %>';
 
+
+const Hihi: React.FC = () => {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '100vh',
+        padding: '2rem',
+        backgroundColor: '#f9f9f9',
+        color: '#333',
+        fontFamily: 'sans-serif',
+        textAlign: 'center',
+      }}
+    >
+      <h1
+        style={{
+          fontSize: '1.5rem',
+        }}
+      >
+        Hihi :)
+      </h1>
+
+      <h2
+        style={{
+          fontSize: '1.0rem',
+          marginBottom: '1rem',
+        }}
+      >
+        No visuals are mounted yet
+      </h2>
+
+      <p
+        style={{
+          fontSize: '1rem',
+          maxWidth: '400px',
+          lineHeight: 1.4,
+          marginBottom: '2rem',
+        }}
+      >
+        You haven’t created a runtime visual or just didn't mount it in the Expo
+        application. Once you add one, open{' '}
+        <span
+          style={{
+            backgroundColor: '#eaeaea',
+            padding: '0.2rem 0.4rem',
+            borderRadius: '4px',
+            fontFamily: 'monospace',
+          }}
+        >
+          app.tsx
+        </span>{' '}
+        and uncomment the{' '}
+        <span
+          style={{
+            backgroundColor: '#eaeaea',
+            padding: '0.2rem 0.4rem',
+            borderRadius: '4px',
+            fontFamily: 'monospace',
+          }}
+        >
+          &lt;UnisphereRuntimeVisual /&gt;
+        </span>{' '}
+        component to see it render here.
+      </p>
+
+      <pre
+        style={{
+          backgroundColor: '#fff',
+          padding: '1rem',
+          border: '1px solid #ddd',
+          borderRadius: '4px',
+          overflowX: 'auto',
+          fontFamily: 'monospace',
+          textAlign: 'left',
+        }}
+      >
+        {`<UnisphereRuntimeVisual
+  widgetName="unisphere.widget.<%= widgetName__lowerDashCase %>"
+  runtimeName="<%= runtimeName__lowerDashCase %>"
+  visualType="-- provide here the visual name --"
+  visualSettings={{
+    -- provide here the visual settings --
+  }}
+/>`}
+      </pre>
+    </div>
+  );
+};
+
 export function AppContent() {
   const { configuration } = useContext(ConfigurationContext);
 
@@ -22,18 +114,18 @@ export function AppContent() {
     () => {
       /*
       Developer Note:
-      • You don’t need to touch the code to enable runtime configuration.
+      The Expo app lets you provide runtime configuration as a JSON object that matches the same schema used in your production or staging environments.
 
-      • If this runtime is already active in an app:
-	      1.	Open Unisphere, press Cmd + K, then choose Manage Workspace Runtimes.
-	      2.	Find the runtime you want, click … (Action), and select Copy Settings.
-	      3.	Paste into NVQ2 with a valid host—settings will be ready to go.
+      •	If the runtime is already active in production or staging:
+        1.	Open Unisphere (Cmd + K) and choose Manage Workspace Runtimes.
+        2.	Locate your runtime, click the ••• (Actions) menu, and select Copy Settings.
+        3. Open the Expo app in the browser, in the header click on the settings icon and paste the JSON into the settings field.
+        4. Use the Save button to persist your settings. They’ll be stored in local storage and automatically loaded the next time the app runs.
 
-      • If the runtime isn’t yet in use:
-	      1.	Manually create the JSON payload matching the runtime’s schema.
-
-      Once you run the application you will have a button where you can save the configurations. 
-      The application will save it in the local storage and will load it on the next run.
+      •	If the runtime isn’t yet in use:
+        1.	Manually create a JSON payload that conforms to your runtime’s schema.
+        2. Open the Expo app in the browser, in the header click on the settings icon and paste the JSON into the settings field.
+        3. Use the Save button to persist your settings. They’ll be stored in local storage and automatically loaded the next time the app runs.
       */
 
       try {
@@ -95,6 +187,8 @@ export function AppContent() {
               onWorkspaceLoaded={onWorkspaceLoaded}
               initialConfiguration={initialConfiguration}
             >
+              <Hihi />
+
               {/* <UnisphereRuntimeVisual
                 widgetName="unisphere.widget.<%= widgetName__lowerDashCase %>"
                 runtimeName="<%= runtimeName__lowerDashCase %>"

package/dist/generators/add-package/add-package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-package.d.ts","sourceRoot":"","sources":["../../../src/generators/add-package/add-package.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,IAAI,EAAiB,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAkBrD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,yBAAyB,uBAwGnC;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"add-package.d.ts","sourceRoot":"","sources":["../../../src/generators/add-package/add-package.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,IAAI,EAAiB,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAuGrD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,yBAAyB,uBAyGnC;AAED,eAAe,mBAAmB,CAAC"}

package/dist/generators/add-package/add-package.js

@@ -5,6 +5,82 @@ const tslib_1 = require("tslib");
 const devkit_1 = require("@nx/devkit");
 const path = tslib_1.__importStar(require("path"));
 const utils_1 = require("../utils");
+function generateDemoComponent(tree, projectRoot, vars) {
+    // path: packages/<pkg>/src/lib/panel-demo.tsx
+    const targetPath = `${projectRoot}/src/lib/${vars['packageName__lowerDashCase']}-demo.tsx`;
+    // component and logger names
+    const loggerName = `${vars['packageName__lowerDashCase']}-demo`;
+    const demoName = `${vars['packageName__pascalCase']}Demo`;
+    const content = `import { useContext, useEffect } from 'react';
+import {
+  ScopedUnisphereWorkspaceContext,
+  useGetScopedWorkspaceLogger,
+} from '@unisphere/runtime-react';
+
+const Hihi = () => {
+  return (
+    <div
+      style={{
+        border: '2px dashed #888',
+        borderRadius: '8px',
+        padding: '2rem',
+        margin: '2rem auto',
+        maxWidth: '500px',
+        textAlign: 'center',
+        fontFamily: 'sans-serif',
+        color: '#444',
+        backgroundColor: '#fcfcfc',
+      }}
+    >
+      <h2
+        style={{
+          marginBottom: '1rem',
+          fontSize: '1.25rem',
+          fontWeight: 500,
+        }}
+      >
+        Hihi :)
+      </h2>
+      <p
+        style={{
+          lineHeight: 1.5,
+          marginBottom: '1.5rem',
+          fontSize: '1rem',
+        }}
+      >
+        This '${demoName}' component shows you how to connect with the Unisphere workspace and set up a scoped logger.
+      </p>
+    </div>
+  );
+};
+
+export const ${demoName} = () => {
+  const { unisphereWorkspace } = useContext(ScopedUnisphereWorkspaceContext);
+  const logger = useGetScopedWorkspaceLogger({
+    type: 'react',
+    name: '${loggerName}',
+  });
+
+  useEffect(() => {
+    // example only - feel free to remove
+    logger.log('${loggerName} mounted');
+    return () => {
+      logger.log('${loggerName} unmounted');
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!unisphereWorkspace) return;
+    
+    // you can access the unisphere workspace that renders the runtime this component is mounted in
+  }, [unisphereWorkspace]);
+
+  // render your visual
+  return <Hihi />;
+};
+`;
+    tree.write(targetPath, content);
+}
 async function addPackageGenerator(tree, options) {
     // Validate and read .unisphere configuration
     const unisphereConfig = (0, utils_1.validateUnisphereConfig)(tree);
@@ -68,6 +144,7 @@ async function addPackageGenerator(tree, options) {
     });
     // Update tsconfig.base.json with path mapping
     (0, utils_1.updateTsConfigPaths)(tree, packageJsonName, `unisphere/packages/${userInputPackageName}/src/index.ts`);
+    generateDemoComponent(tree, projectRoot, templateVariables);
     await (0, devkit_1.formatFiles)(tree);
     // Return a function that will be executed after all file operations are complete
     return () => {

package/dist/generators/add-package/schema.json

@@ -15,23 +15,23 @@
       "description": "The distribution scope of the package",      
       "default": "none",
       "x-prompt": {
-        "message": "What scope should this package have?",
-        "type": "list",
-        "items": [
-          {
-            "value": "none",
-            "label": "None (no scope) - Private repository only"
-          },          
-          {
-            "value": "internal",
-            "label": "Internal (@kaltura/unisphere-) - Published to GitHub packages"
-          },
-          {
-            "value": "public",
-            "label": "Public (@unisphere/) - Published to npm"
-          }
-        ]
+    "message": "What scope should this package have? If you’re unsure, choose Private.",
+    "type": "list",
+    "items": [
+      {
+        "value": "none",
+        "label": "Private – only for this Unisphere experience (not published externally)"
+      },
+      {
+        "value": "internal",
+        "label": "Kaltura – published as a GitHub package (@kaltura/unisphere-… for Kaltura teams)"
+      },
+      {
+        "value": "public",
+        "label": "Public – published to npm (@unisphere/… available to everyone)"
       }
+    ]
+  }   
     }
   },
   "required": [

package/dist/generators/add-package/templates/new-package/src/index.ts.template

@@ -0,0 +1 @@
+export * from './lib/<%= packageName__lowerDashCase %>-demo';

package/dist/generators/add-package/templates/new-package/tsconfig.lib.json

@@ -19,5 +19,5 @@
     "**/*.spec.jsx",
     "**/*.test.jsx"
   ],
-  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.ts", "src/**/*.tsx"]
+  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.ts", "src/**/*.tsx", "src/index.ts.template"]
 }

package/dist/generators/add-runtime/add-runtime.js

@@ -69,17 +69,17 @@ async function addRuntimeGenerator(tree, options) {
     const runtimePathKey = `unisphere-runtime-${userInputRuntimeName}`;
     const runtimePathValue = `unisphere/runtimes/${userInputRuntimeName}/src/index.ts`;
     (0, utils_1.updateTsConfigPaths)(tree, runtimePathKey, runtimePathValue);
+    // Create a package with the same name as the runtime and distribution set to none
+    const packageResult = await (0, add_package_1.addPackageGenerator)(tree, {
+        packageName: userInputRuntimeName,
+        scope: 'none',
+    });
+    // Execute the package generation callback if it exists
+    if (packageResult && typeof packageResult === 'function') {
+        packageResult();
+    }
     // Handle loadedByExternalHost usage - create package and expo application
     if (options.usage === 'loadedByExternalHost') {
-        // Create a package with the same name as the runtime and distribution set to none
-        const packageResult = await (0, add_package_1.addPackageGenerator)(tree, {
-            packageName: userInputRuntimeName,
-            scope: 'none',
-        });
-        // Execute the package generation callback if it exists
-        if (packageResult && typeof packageResult === 'function') {
-            packageResult();
-        }
         // Create an expo application without prompts
         const applicationResult = await (0, add_application_1.addApplicationGenerator)(tree, {
             name: `${userInputRuntimeName}-expo`,

package/dist/generators/add-runtime/schema.d.ts

@@ -1,4 +1,4 @@
 export interface AddRuntimeGeneratorSchema {
   name: string;
-  usage: 'loadedByExternalHost' | 'embeddedInWidgetPlayground';
+  usage: 'loadedByExternalHost' | 'composedIntoAnotherRuntime';
 }

package/dist/generators/add-runtime/schema.json

@@ -19,12 +19,12 @@
         "items": [
           {
             "value": "loadedByExternalHost",
-            "label": "Loaded by External Host (requires separate package and Expo playground)"
+            "label": "Independent experience used as an entry point (loaded by host or another experience)"
           },
           {
-            "value": "embeddedInWidgetPlayground",
-            "label": "Embedded in Widget Playground (no separate package or playground needed)"
-          }
+            "value": "composedIntoAnotherRuntime",
+            "label": "Composed into another runtime of this experience (not used as an entry point)"
+          }         
         ]
       }
     }

package/dist/generators/add-runtime/templates/new-runtime/src/lib/runtime.tsx.template

@@ -31,6 +31,9 @@ export class Runtime
   }
 
   constructor(options: CreateElementOptions<<%= runtimeName__pascalCase %>RuntimeSettings>) {
+    /*
+    Developer Note: to generate a visual run `npx nx g @unisphere/nx:add-visual`
+    */
     super({
       ...options,
       settingsSchema: <%= runtimeName__camelCase %>RuntimeSettingsSchema,

package/dist/generators/add-visual/templates/new-visual/render-method.template

@@ -9,7 +9,7 @@
   this._logger.log('rendering <%= visualName__humanReadable %>');
 
   visual.htmlContainer?.render(
-    <ScopedUnisphereWorkspaceProvider unisphereWorkspace={this._workspace}>
+    <ScopedUnisphereWorkspaceProvider unisphereWorkspace={this._workspace} runtimeLogger={this._logger}>
       <ThemeProvider
         cssPrefix={'<%= widgetName__lowerDashCase %>-<%= runtimeName__lowerDashCase %>-<%= visualName__lowerDashCase %>'}
         mode={typeof this._theme === 'string' ? this._theme : this._theme.mode}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unisphere/nx",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "private": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -75,7 +75,8 @@
   },
   "dependencies": {
     "@nx/devkit": "21.2.1",
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "ts-morph": "^26.0.0"
   },
   "generators": "./generators.json",
   "files": [

package/dist/generators/add-package/templates/new-package/src/index.ts

@@ -1 +0,0 @@
-export {};