Create an App

Overview #

JoonWeb provides a flexible and open app ecosystem that enables developers to extend, enhance, and integrate custom functionality into JoonWeb websites and online stores. As a JoonWeb Technology Partner, you can build apps using any programming language (such as PHP or Node.js) and any database (including MySQL, SQLite, or others). Apps can be embedded into JoonWeb or used to extend platform capabilities through structured extensions. This document explains how to scaffold, run, and test a JoonWeb app using the official JoonWeb CLI.

What You Can Build on JoonWeb #

# What You Can Build on JoonWeb JoonWeb supports multiple app types depending on the level of integration required. --- ## 1. Embedded Apps Embedded apps allow you to add new functionality inside the JoonWeb environment, similar to loading scripts or widgets. ### Common Use Cases - Custom dashboards - Third-party service integrations - Analytics, automation, or AI tools --- ## 2. App Extensions App extensions allow you to extend core JoonWeb functionality **without modifying the platform itself**. ### Available Extension Types #### Theme Extension Enables live changes on customer websites, such as: - UI components - Dynamic sections - Interactive elements #### App Embed Inject functionality using script-based embeds (similar to `<script>` tags). #### App Sections Add configurable sections that merchants can control from the editor. #### App Blocks Modular blocks that can be placed inside sections for **fine-grained customization**.

Prerequisites #

Before you begin app development, ensure the following requirements are met: - **Active JoonWeb Technology Partner Account** - **JoonWeb CLI installed** Install using: ```bash npm -g i @joonweb/joonweb-cli

Getting Started: Create Your First App #

## Step 1: Initialize a New App 1. Open your **terminal** or **command prompt**. 2. Navigate to the directory where you want to create your app. A new subdirectory will be created automatically. 3. Run the following command: ```bash joonweb app init

Creating App Extensions #

if your app requires extensions, they must be generated using the JoonWeb CLI. ## Generate an Extension Run the following command: ```bash joonweb app generate extension ``` The CLI will automatically: - Register the extension - Create the required folder structure and configuration file - Link the extension to your app configuration --- ## Extension Folder Structure ``` your-app/ ├── extensions/ │ └── your-extension/ │ ├── blocks/ # Your Blocks in .jw will be listed here │ ├── components/ # Your snippets in .jw will be listed here │ ├── assets/ # Your CSS, JS, images, etc. │ └── joonweb.extension.json # Extension manifest file └── joonweb.app.json # App manifest file ``` --- ## Extension Configuration Once the extension is created, you can configure it inside: `joonweb.extension.json` Example configuration: ```json { "name": "MY Extension", "handle": "smart-floating", "type": "theme_app_extension", "extension_key": "", "blocks": [ { "type": "app-sections", "name": "My Section", "target": "section", "src": "blocks/your-section_or_block.jw" } ], "uid": "7e24ff92-9362-4765-8909-1db290511f" } ``` ### Field Explanation - **name** → Name of your extension (appears in the builder) - **handle** → Internal handle (DO NOT CHANGE) - **type** → Extension type (DO NOT CHANGE) - **extension_key** → Internal system key - **blocks** → Defines sections or embeds - **uid** → Unique identifier (DO NOT CHANGE) --- ## Important ⚠️ Do **not copy extension folders from other apps**. Each extension is uniquely registered with its parent app. Copying folders between apps may cause: - Extension registration failures - Deployment errors - Broken references

Test Your App in Development Mode #

To test your app locally: 1. Navigate to your **app directory**. 2. Run the development server using the command below: ```bash joonweb app serve ``` 3. When prompted, select your **JoonWeb Development Store**. The CLI will automatically open a browser window for: - **App installation** - **Scope authorization** After authorization, your app will be connected to the **development store** and ready for testing.

Required App Components #

All JoonWeb apps must correctly implement the following components: ## SessionStorage Handles **secure session management** for your app. ## JoonWeb API Used for communication between your app and the **JoonWeb platform**. ## App Bridge Connects your **embedded app** with the **JoonWeb admin interface**.

Deploying Your App #

After development and testing, you can deploy your app. Run the following command: ```bash joonweb app deploy ``` This command will: - Create a **new app version** - Save the version as a **draft** - Prompt you to **release the version**

Releasing a Version #

If you choose to release the version: - The update becomes **available to existing users** who have installed the app.

Publishing to the Marketplace #

Running `joonweb app deploy` does **not** publish the app to the marketplace. To publish your app publicly: 1. Log in to your **JoonWeb Partner Account**. 2. Complete the **App Distribution** process. 3. Submit the app for **approval**. After approval, the app will appear in the **JoonWeb App Marketplace**.

Common Issues & Solutions #

## Port Already Open **Error:** `ERR: already port open` **Solution:** ```bash joonweb app refresh ``` Then start the development server again. --- ## Deployment Failed If deployment fails: 1. Read the **error message** carefully. 2. Verify the following: - Required files exist - Extensions are registered properly - Credentials are valid 3. Fix the issue and deploy again. --- # Development Workflow Summary Basic workflow for building a JoonWeb app: 1. **Initialize the app** ```bash joonweb app init ``` 2. **Generate extensions** ```bash joonweb app generate extension ``` 3. **Start development server** ```bash joonweb app serve ``` 4. **Build and test features** 5. **Deploy the app** ```bash joonweb app deploy ``` 6. **Publish through the Partner Dashboard**