@unisphere/nx 1.1.2 → 1.1.4

package/README.md

@@ -2,13 +2,16 @@
 
 > 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
 
-## 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](https://www.npmjs.com/package/create-unisphere-project) npm package with all necessary tooling and structure, run:
 
@@ -16,13 +19,6 @@ To scaffold a new project you can use [create-unisphere-project](https://www.npm
 npm create unisphere-project@latest
 ```
 
-> ⚠️ **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.
-
-**Before running the command**, make sure you have a valid `GITHUB_TOKEN` exported in your environment. This is required for GitHub operations during setup.
-
----
-
 ### 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.
@@ -36,7 +32,7 @@ Please contact **Eran Sakal** or **Omri Ceisler** to provision the repository. T
    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).
+   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.
@@ -48,7 +44,7 @@ Once created, you can push your local project into the new repository and begin
 
 ---
 
-## Use the `@unisphere/nx` Plugin
+## 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.
 
@@ -91,8 +87,6 @@ npx nx g @unisphere/nx:add-runtime
 
     - 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.
@@ -108,8 +102,6 @@ npx nx g @unisphere/nx:add-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.
@@ -133,8 +125,6 @@ npx nx g @unisphere/nx:add-application
 
 - **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.
@@ -161,8 +151,6 @@ npx nx g @unisphere/nx:add-package
   - **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.
@@ -173,8 +161,6 @@ npx nx g @unisphere/nx:add-package
 
 🔍 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

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

@@ -5,11 +5,103 @@ import { ConfigurationContext } from './configuration-provider';
 import { isConfigurationValid } from './definitions';
 import { Header } from './components/header';
 import { ConfigurationProvider } from './configuration-provider';
-import { UnisphereProvider } from '@unisphere/runtime-react';
+import { UnisphereProvider, UnisphereRuntimeVisual } from '@unisphere/runtime-react';
 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-application/templates/interactive-playground/src/app/components/settings-form.tsx

@@ -92,11 +92,15 @@ export const SettingsForm: React.FC = () => {
           name={'settings'}
           fullWidth
           inputProps={{
-            ...register('settings', { required: true }),
+            ...register('settings', {
+              required: `To pass empty settings, type "{}". Otherwise: (1) manually type valid JSON. (2) `,
+            }),
           }}
           label={'Unisphere Settings'}
-          helperText={`Easily copy settings from Unisphere by entering a workable host in NVQ2 and then do: Unisphere cmd+k > Manage Workspace Runtimes > show ... (actions) of desired runtime > copy settings`}
-          error={!!errors?.settings}
+          helperText={`${
+            errors?.settings?.message || ''
+          }Easily copy settings from Unisphere by entering a workable host in NVQ2 and then do: Unisphere cmd+k > Manage Workspace Runtimes > show ... (actions) of desired runtime > copy settings`}
+          error={!!errors?.settings?.message}
         />
       </FormCard>
     </Stack>

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? If you are not sure what to choose, choose None.",
-        "type": "list",
-        "items": [
-          {
-            "value": "none",
-            "label": "None (no scope) - Used only internally by the experience runtimes."
-          },          
-          {
-            "value": "internal",
-            "label": "Internal - Published to GitHub packages (@kaltura/unisphere-<experience-name>-<package-name>)"
-          },
-          {
-            "value": "public",
-            "label": "Public - Published to npm (@unisphere/<experience-name>-<package-name>)"
-          }
-        ]
+    "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/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.2",
+  "version": "1.1.4",
   "private": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

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