@unifyapps/custom-component-cli 0.0.2 → 0.0.3

package/Readme.md

@@ -0,0 +1,124 @@
+# Add Custom Component
+
+Unify lets you extend your app experience with **Custom Components**. This guide walks you through building a Component using the **Custom Component CLI**.
+
+## Step-by-Step: Build Your First Component
+
+### Step 1: Initialize a New Component
+
+Start by scaffolding a new Component using the CLI. This creates a ready-to-edit project with a sample React component.
+
+```bash
+pnpx @unifyapps/custom-component-cli init <ComponentName>
+```
+
+This creates a folder `<ComponentName>/` with:
+
+* `package.json` – project metadata
+* `manifest.json` – config for Unify
+* `src/index.jsx` – the main React component
+* `src/style.css` – component styles
+
+Navigate into the component directory:
+
+```bash
+cd <ComponentName>
+```
+
+**Example manifest format generated after initialization:**
+
+```json
+{
+  "name": "SuperButton",
+  "type": "SuperButton",
+  "entry": "./src/index.jsx",
+  "keywords": "SuperButton",
+  "style": "./src/style.css",
+  "icon": "https://assets.unifyapps.com/user-uploads/theme/unify.svg"
+}
+```
+
+* **keywords** – used for block search in the block picker
+* **icon** – URL of the icon to display in the block picker (optional)
+
+You can add icon and modify the keywords before using the manifest in Unify.
+
+### Step 2: Run in Development Mode
+
+To preview your Component as you build, run in development mode.  
+**Note:** The development server will only be accessible on your local machine.
+
+```bash
+pnpm run dev
+```
+
+Or
+
+```bash
+pnpx @unifyapps/custom-component-cli dev
+```
+
+Once started, the CLI hosts the manifest at a local URL like:
+
+```
+http://localhost:5001/super-button.json
+```
+
+You'll use this in the next step.
+
+### Step 3: Add the Component in Unify
+
+To make your component available inside Unify:
+
+1. Go to Custom Components Manager
+2. Click **Add Component** and fill in:
+   * **Component Name** – e.g., SuperButton
+   * **Deployment Mode** – Select development mode for testing
+   * **Manifest URL** – The local URL from dev mode
+
+On Clicking **Add**, Your Component will be added 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 to prepare it for deployment:
+
+```bash
+pnpm run build
+```
+
+Or
+
+```bash
+pnpx @unifyapps/custom-component-cli build
+```
+
+This creates a `<ComponentName>.zip` containing:
+
+* Compiled assets
+* A production out.json manifest
+
+### Step 6: Adding Component to Production
+
+Open the **Component Detail** panel and click the three-dot menu next to the manifest URL.
+
+1. From the dropdown, select **Move to Production** to promote the version.
+2. Upload the zip file
+
+Your Component is now live and ready to use across your Unify interfaces.
+
+### Step 7: Removing a Component
+
+To remove a Component:
+
+1. Remove the component from all apps where it is used (make sure it is not referenced or configured anywhere).
+2. After all usages are removed, go to the Custom Components Manager and delete the component from the list.
+
+> note: if you skip step 1 and delete the component from the list, any apps still referencing it may break or show errors.
+
+**You're All Set!**
+
+With these steps, you can **build, test, and ship** custom Components in Unify with full flexibility. Components empower your team to reuse UI logic and deliver richer, more tailored app experiences.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifyapps/custom-component-cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -13,10 +13,10 @@
     "cli.js",
     "manifestPlugin.js",
     "entryMountTemplate.js",
-    "CREATING_CUSTOM_BLOCK.md"
+    "Readme.md"
   ],
   "lint-staged": {
-    "*.{md,css,gql,graphql,json}": "biome check --linter-enabled=false --write",
+    "*.{css,gql,graphql,json}": "biome check --linter-enabled=false --write",
     "*.{js,jsx,ts,tsx}": [
       "oxlint --fix",
       "biome check --linter-enabled=false --write"
@@ -36,8 +36,5 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4"
   },
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build"
-  }
+  "scripts": {}
 }

package/templates/init/.gitignore.mustache

@@ -0,0 +1,9 @@
+node_modules
+.ua-entry-mount.js
+dist
+{{kebabName}}.zip
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local

package/CREATING_CUSTOM_BLOCK.md

@@ -1,111 +0,0 @@
-# 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.