@unifyapps/custom-component-cli 0.0.1

package/CREATING_CUSTOM_BLOCK.md

@@ -0,0 +1,111 @@
+# Creating a Custom Block with the Block CLI
+
+This guide explains how to build and register a Custom Block using the block CLI. Blocks can be served locally for development and then exported for use in the Unify application.
+
+## 0. Initialize a new Block
+
+To scaffold a new block with a simple React component, package.json, and a manifest.json, run:
+
+```bash
+pnpx @unifyapps/block-cli init <BlockName>
+```
+
+This creates a new `<BlockName>/` folder containing:
+- `package.json`
+- `manifest.json`
+- `src/index.jsx`
+- `src/style.css`
+
+```bash
+cd <BlockName>
+```
+
+## 1. Set up your workspace
+
+Navigate to the directory containing the React component you want to expose as a Block. The CLI commands should be executed from this path so that relative imports resolve correctly.
+
+```bash
+cd path/to/project
+```
+
+## 2. Start the Block in development mode
+
+With a `manifest.json` in your project folder, you can simply run:
+
+```bash
+pnpx @unifyapps/block-cli dev
+```
+
+You can still override using CLI arguments:
+
+```bash
+pnpx @unifyapps/block-cli dev <BlockName> <component-path>
+```
+
+Example (using manifest):
+
+```bash
+pnpx @unifyapps/block-cli dev
+```
+
+The CLI serves the block manifest at `http://localhost:5001/super-button.json`. Note this URL for the next step.
+
+## 3. Register the Block in the Unify app
+
+1. Visit `qa.unifyapps.com/p/0/object/custom_blocks/records`.
+2. Click **Add Record** and fill out the form:
+   - **BlockName** – the name used in the CLI, e.g. `SuperButton`.
+   - **Manifest URL** – the local URL from the previous step.
+3. Save the record.
+
+Once saved, the Block appears in the Application Builder under the **components** section. You can now test it in your interfaces.
+
+## 4. Iterate on the Block
+
+While running in `dev` mode, any changes to the component are reflected automatically. Refresh the Application Builder to load the latest version.
+
+## 5. Build the Block for production
+
+After testing, build a production bundle. From your project folder with a `manifest.json`, run:
+
+```bash
+pnpx @unifyapps/block-cli build
+```
+
+Or override using CLI arguments:
+
+```bash
+pnpx @unifyapps/block-cli build <BlockName> <component-path>
+```
+
+Example (using manifest):
+
+```bash
+pnpx @unifyapps/block-cli build
+```
+
+The CLI outputs a `dist` directory containing the compiled block files, an `out.json` manifest, and a `<BlockName>.zip` archive of the `dist/` folder.
+
+## 6. Upload the build output
+
+1. Upload the contents of the `dist` directory to the Unify app.
+2. Update the record created earlier with the new **Manifest URL** pointing to your uploaded `out.json`.
+
+## 7. Removing a Block
+
+To remove a Block from the system, delete its record from the custom blocks page in the Unify app.
+
+## 8. Additional CLI examples
+
+While the CLI will eventually be published, you can run it directly from this repository:
+
+```bash
+pnpx /path/to/www/packages/block-cli dev
+pnpx /path/to/www/packages/block-cli build
+```
+
+Replace `/path/to/www` with the absolute path on your machine.
+
+---
+
+With these steps you can develop, test, and deploy custom Blocks to extend the Unify platform.

package/cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import {
+  createWriteStream,
+  existsSync,
+  readFileSync,
+  unlinkSync,
+  watch,
+  writeFileSync,
+} from 'node:fs';
+import http from 'node:http';
+import { dirname, resolve } from 'node:path';
+import { optimizeLodashImports } from '@optimize-lodash/rollup-plugin';
+import react from '@vitejs/plugin-react-swc';
+import archiver from 'archiver';
+import _kebabCase from 'lodash/kebabCase.js';
+import preserveDirectives from 'rollup-preserve-directives';
+import handler from 'serve-handler';
+import { build } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { getEntryMountCode } from './entryMountTemplate.js';
+import { initComponent } from './init.js';
+import manifestPlugin from './manifestPlugin.js';
+
+const mode = process.argv[2] ?? 'dev';
+if (mode === 'init') {
+  initComponent(process.argv[3]);
+  process.exit(0);
+}
+// load user manifest if present
+let manifest = {};
+if (existsSync(resolve(process.cwd(), 'manifest.json'))) {
+  manifest = JSON.parse(readFileSync(resolve(process.cwd(), 'manifest.json'), 'utf-8'));
+}
+const PackageName = manifest.type ?? process.argv[3];
+const userEntryRel = manifest.entry ?? process.argv[4];
+if (!PackageName || !userEntryRel) {
+  console.error(
+    '\n❌ Error: Missing component name or entry. Provide via CLI arguments or manifest.json\n',
+  );
+  process.exit(1);
+}
+const root = resolve(process.cwd(), userEntryRel);
+const libName = _kebabCase(PackageName);
+const distDir = resolve(process.cwd(), 'dist');
+
+const WRAPPER_FILENAME = '.ua-entry-mount.js';
+const wrapperPath = resolve(process.cwd(), WRAPPER_FILENAME);
+
+function createWrapperFile() {
+  writeFileSync(wrapperPath, getEntryMountCode(userEntryRel));
+}
+
+function cleanupWrapperFile() {
+  try {
+    unlinkSync(wrapperPath);
+  } catch {
+    // ignore
+  }
+}
+
+function patchViteConfigWithWrapper(config) {
+  config.build = {
+    ...config.build,
+    lib: {
+      ...config.build.lib,
+      entry: wrapperPath,
+    },
+  };
+  return config;
+}
+
+function getViteConfig() {
+  return {
+    plugins: [
+      tsconfigPaths(),
+      react(),
+      preserveDirectives(),
+      optimizeLodashImports(),
+      manifestPlugin(),
+    ],
+    define: {
+      'process.env': { NODE_ENV: process.env.NODE_ENV ?? 'development' },
+    },
+    build: {
+      lib: {
+        entry: root,
+        name: PackageName,
+        formats: ['es'],
+        fileName: (format) => `${libName}.${format}.js`,
+        cssFileName: libName,
+      },
+    },
+  };
+}
+
+const DEV_SERVER_PORT = process.env.PORT || 5001;
+
+async function runDevServer() {
+  createWrapperFile();
+  const config = patchViteConfigWithWrapper(getViteConfig());
+  let server;
+
+  async function startServer() {
+    if (server) await server.close();
+    server = http.createServer((request, response) =>
+      handler(request, response, {
+        public: distDir,
+        directoryListing: false,
+        headers: [
+          {
+            source: '**',
+            headers: [{ key: 'Access-Control-Allow-Origin', value: '*' }],
+          },
+        ],
+      }),
+    );
+    server.listen(DEV_SERVER_PORT, () => {
+      console.log(`\n✅ Development server started`);
+      console.log(`📡 Serving manifest at: http://localhost:${DEV_SERVER_PORT}/out.json`);
+      console.log(`\n💡 Add this URL in Unify's Custom Components Manager`);
+      console.log(`🔄 Watching for file changes...\n`);
+    });
+  }
+
+  await build({ ...config, build: { ...config.build } });
+  await startServer();
+
+  const watchDir = dirname(resolve(process.cwd(), userEntryRel));
+  console.log(`Watching directory: ${watchDir}`);
+  const watcher = watch(watchDir, { recursive: true }, async (_eventType, filename) => {
+    if (filename && /\.(ts|tsx|js|jsx|css)$/.test(filename)) {
+      console.log(`File ${filename} changed. Rebuilding...`);
+      try {
+        await build({ ...config, build: { ...config.build } });
+        console.log('Rebuild completed successfully');
+      } catch (error) {
+        console.error('❌ Build failed:', error);
+      }
+    }
+  });
+
+  process.on('SIGINT', async () => {
+    console.log('\n\n🛑 Stopping development server...');
+    watcher.close();
+    if (server) await server.close();
+    cleanupWrapperFile();
+    console.log('✅ Server stopped\n');
+    process.exit(0);
+  });
+}
+
+switch (mode) {
+  case 'dev': {
+    await runDevServer();
+    break;
+  }
+  case 'build': {
+    console.log('\n🔨 Building component for production...\n');
+    createWrapperFile();
+    const config = patchViteConfigWithWrapper(getViteConfig());
+    await build(config);
+    cleanupWrapperFile();
+    // Zip up the dist directory
+    const zipName = `${libName}.zip`;
+    const zipPath = resolve(process.cwd(), zipName);
+    await new Promise((resolveZip, rejectZip) => {
+      const output = createWriteStream(zipPath);
+      const archive = archiver('zip', { zlib: { level: 9 } });
+      output.on('close', resolveZip);
+      archive.on('error', rejectZip);
+      archive.pipe(output);
+      archive.directory(distDir, false);
+      archive.finalize();
+    });
+    console.log(`\n✅ Production package created: ${zipName}`);
+    console.log(
+      `💡 Move the dev version to production and upload this file in Unify's Custom Components Manager\n`,
+    );
+    break;
+  }
+  default:
+    throw new Error('Invalid mode');
+}

package/entryMountTemplate.js

@@ -0,0 +1,16 @@
+// Generates the entry-mount wrapper code for the build
+// userEntryRel: relative path to the user's entry file (string)
+export function getEntryMountCode(userEntryRel) {
+  return `import React from "react";
+import { createRoot } from "react-dom/client";
+import Component from "${userEntryRel}";
+const domNode = document.getElementById("ua-custom-block");
+const reactRoot = domNode ? createRoot(domNode) : null;
+window.renderComponent = (props) => {
+  if (reactRoot) {
+    reactRoot.render(React.createElement(Component, props));
+  }
+};
+export default Component;
+`;
+}

package/init.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import _capitalize from 'lodash/capitalize.js';
+import _kebabCase from 'lodash/kebabCase.js';
+import mustache from 'mustache';
+
+/**
+ * Scaffold a new React Custom Component project in a folder named after componentName,
+ * using templates with Mustache placeholders.
+ */
+export function initComponent(componentName) {
+  if (!componentName) {
+    console.error('❌ Error: Component name is required');
+    process.exit(1);
+  }
+
+  console.log(`🚀 Initializing custom component: ${componentName}`);
+
+  const projectDir = resolve(process.cwd(), componentName);
+  if (existsSync(projectDir)) {
+    console.error(`❌ Error: Directory '${componentName}' already exists`);
+    process.exit(1);
+  }
+
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const templatesDir = resolve(__dirname, 'templates', 'init');
+  const kebabName = _kebabCase(componentName);
+  const capitalName = _capitalize(componentName);
+
+  function copyTemplates(srcDir) {
+    for (const name of readdirSync(srcDir)) {
+      const srcPath = resolve(srcDir, name);
+      const relPath = srcPath.slice(templatesDir.length + 1);
+      const stats = statSync(srcPath);
+      if (stats.isDirectory()) {
+        copyTemplates(srcPath);
+      } else if (stats.isFile()) {
+        const outRel = relPath.replace(/\.mustache$/, '');
+        const destPath = resolve(projectDir, outRel);
+        mkdirSync(dirname(destPath), { recursive: true });
+        const template = readFileSync(srcPath, 'utf-8');
+        const content = mustache.render(template, { componentName, kebabName, capitalName });
+        writeFileSync(destPath, content, 'utf-8');
+      }
+    }
+  }
+
+  copyTemplates(templatesDir);
+
+  console.log(`
+    ✅ Successfully initialized custom component in ./${componentName}
+    
+    📝 Next steps:
+      1. cd ${componentName}
+      2. pnpm i
+      3. Open the project in your code editor and customize your component
+      4. pnpm run dev
+      5. Create a custom component and add the development URL in Unify's Custom Components Manager
+      6. pnpm run build
+      7. Move the dev version to production and upload the ${kebabName}.zip file in Unify's Custom Components Manager
+    
+    📖 See README.md for detailed instructions
+    `);
+}

package/manifestPlugin.js

@@ -0,0 +1,36 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Rollup plugin that reads the user-defined manifest.json and updates
+ * the output manifest with actual build asset filenames.
+ */
+export default function manifestPlugin() {
+  return {
+    name: 'custom-component-cli-manifest',
+    enforce: 'post',
+    apply: 'build',
+    async writeBundle(options, bundle) {
+      const baseManifest = JSON.parse(
+        await readFile(resolve(process.cwd(), 'manifest.json'), 'utf-8'),
+      );
+      const entryAsset = Object.values(bundle).find((o) => o.isEntry);
+      if (!entryAsset || !entryAsset.exports?.includes('default')) {
+        throw new Error(
+          `Could not find default export in entry ${entryAsset?.facadeModuleId || 'unknown'}`,
+        );
+      }
+      const styleAsset = Object.values(bundle).find((o) => o.fileName.endsWith('.css'));
+
+      const { entry: _, ...staticFields } = baseManifest;
+      const manifest = {
+        ...staticFields,
+        main: entryAsset.fileName,
+        style: styleAsset?.fileName,
+      };
+
+      const filePath = resolve(options.dir, 'out.json');
+      await writeFile(filePath, JSON.stringify(manifest, null, 2));
+    },
+  };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@unifyapps/custom-component-cli",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": "./cli.js",
+  "type": "module",
+  "main": "cli.js",
+  "files": [
+    "templates",
+    "init.js",
+    "cli.js",
+    "manifestPlugin.js",
+    "entryMountTemplate.js",
+    "CREATING_CUSTOM_BLOCK.md"
+  ],
+  "lint-staged": {
+    "*.{md,css,gql,graphql,json}": "biome check --linter-enabled=false --write",
+    "*.{js,jsx,ts,tsx}": [
+      "oxlint --fix",
+      "biome check --linter-enabled=false --write"
+    ]
+  },
+  "dependencies": {
+    "@optimize-lodash/rollup-plugin": "^5.0.2",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@vitejs/plugin-react-swc": "^4.2.0",
+    "archiver": "^5.3.1",
+    "lodash": "^4.17.21",
+    "mustache": "^4.2.0",
+    "rollup-plugin-visualizer": "^5.14.0",
+    "rollup-preserve-directives": "^1.1.3",
+    "serve-handler": "^6.1.6",
+    "vite": "^7.2.2",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  }
+}

package/templates/init/README.md.mustache

@@ -0,0 +1,137 @@
+# {{capitalName}} Custom Component
+
+This is a custom component created for UnifyApps. You can develop and customize this component to extend your application's functionality.
+
+## Project Structure
+
+```
+{{componentName}}/
+├── src/
+│   ├── index.jsx      # Main React component file
+│   └── style.css      # Component styles
+├── manifest.json      # Component configuration for Unify
+├── package.json       # Project dependencies and scripts
+└── README.md          # This file
+```
+
+## Manifest Configuration
+
+The `manifest.json` file configures your component for Unify. You can add icon and modify the keywords before using the manifest in Unify:
+
+```json
+{
+  "name": "{{capitalName}}",
+  "type": "{{componentName}}",
+  "entry": "./src/index.jsx",
+  "keywords": "{{componentName}}",
+  "style": "./src/style.css",
+  "icon": "https://assets.unifyapps.com/interface/migrated/theme/unify.svg"
+}
+```
+
+### Fields
+
+- **`name`** (required) - Display name of the component
+- **`type`** (required) - Component type identifier
+- **`entry`** (required) - Path to the main component file
+- **`keywords`** (required) - Search keywords for the block picker
+- **`style`** (optional) - Path to the component stylesheet
+- **`icon`** (optional) - URL of the icon to display in the block picker
+
+## Development
+
+### Where to Develop
+
+All component code should be developed in the `src/` directory:
+
+- **`src/index.jsx`** - Your main React component. This is where you'll write your component logic.
+- **`src/style.css`** - Component-specific styles. Add your CSS here.
+
+The component receives the following props:
+- `data` - Component data state
+- `updateData` - Function to update component data
+- `emitOnClick` - Function to emit click events
+- `emitOnChange` - Function to emit change events
+
+### Next Steps
+
+#### Step 1: Install Dependencies
+
+Install the required dependencies:
+
+```bash
+pnpm i
+```
+
+#### Step 2: Run in Development Mode
+
+Start the development server to preview your component locally. Use the path shown during initialization:
+
+```bash
+pnpm run dev
+```
+
+Once started, the CLI will host the manifest at a local URL like:
+```
+http://localhost:5001/out.json
+```
+
+You'll use this URL in the next step.
+
+#### Step 3: Add the Component in Unify
+
+To make your component available inside Unify:
+
+1. Go to **Custom Components Manager** in your Unify dashboard
+2. Click **Add Component** and fill in:
+   - **Component Name** - e.g., `{{capitalName}}`
+   - **Deployment Mode** - Select **development mode** for testing
+   - **Manifest URL** - The local URL from dev mode (e.g., `http://localhost:5001/out.json`)
+
+On clicking **Add**, your component will be available in the Application Builder **block picker**.
+
+#### Step 4: Instant Reload
+
+While running in `dev` mode, any changes to your React component are instantly reflected. Just refresh the Application Builder to see updates.
+
+#### Step 5: Build for Production
+
+After finalizing and testing your component, generate a production-ready build. Use the same path as in step 2:
+
+```bash
+pnpm run build
+```
+
+This creates a `{{kebabName}}.zip` file containing:
+- Compiled assets
+- A production `out.json` manifest
+
+#### Step 6: Deploy to Production
+
+1. Open the **Component Detail** panel in Unify
+2. Click the three-dot menu next to the manifest URL
+3. Select **Move to Production** from the dropdown
+4. Upload the `{{kebabName}}.zip` file
+
+Your component is now live and ready to use across your Unify interfaces.
+
+## Component Props
+
+Your component receives the following props:
+
+- `data` - Object containing component data state
+- `updateData(newData)` - Function to update component data
+- `emitOnClick()` - Function to emit click events
+- `emitOnChange()` - Function to emit change events
+
+## Removing a Component
+
+To remove this component from your app:
+
+1. Go to the **Custom Components** page in Unify
+2. Delete the corresponding component you want to remove
+
+## Resources
+
+- [UnifyApps Custom Components Documentation](https://www.unifyapps.com/docs/unify-applications/add-custom-component)
+

package/templates/init/manifest.json.mustache

@@ -0,0 +1,7 @@
+{
+  "name": "{{capitalName}}",
+  "type": "{{componentName}}",
+  "entry": "./src/index.jsx",
+  "keywords": "{{componentName}}",
+  "style": "./src/style.css"
+}

package/templates/init/package.json.mustache

@@ -0,0 +1,15 @@
+{
+  "name": "{{kebabName}}",
+  "version": "0.1.0",
+  "private": true,
+  "main": "src/index.jsx",
+  "scripts": {
+    "dev": "pnpx @unifyapps/custom-component-cli dev {{kebabName}}",
+    "build": "pnpx @unifyapps/custom-component-cli build {{kebabName}}"
+  },
+  "dependencies": {
+    "@unifyapps/custom-component-cli": "^0.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  }
+}

package/templates/init/src/index.jsx.mustache

@@ -0,0 +1,19 @@
+import React, { useCallback } from 'react';
+import './style.css';
+
+export default function {{capitalName}}(props) {
+  const { updateData, data, emitOnClick, emitOnChange } = props;
+  const value = data?.value ?? 0;
+
+  const onClick = useCallback(() => {
+    updateData({ value: value + 1 });
+    emitOnClick();
+  }, [value, updateData]);
+
+
+  return (
+    <button className="{{kebabName}}" onClick={onClick}>
+      Button is {value}
+    </button>
+  );
+}

package/templates/init/src/style.css.mustache

@@ -0,0 +1,3 @@
+.{{kebabName}} {
+  /* Add your styles here */
+}