Create an App

Overview #

JoonWeb provides an open and flexible 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 standalone or embedded applications using any tech stack (Node.js, Express, PHP, React, etc.) and any database (MySQL, PostgreSQL, MongoDB, etc.). This guide provides a complete step-by-step walkthrough to initialize, configure, run, and deploy your first JoonWeb app using the official **JoonWeb CLI**.

Requirements #

Before initializing your app, verify that you have met the following requirements: 1. **Partner Account**: You are a registered Technology Partner with app development permissions. Access or create your account at [JoonWeb Partner Portal](https://www.joonweb.com/partners). If you do not have a partner account yet, create one at [https://www.joonweb.com/partners](https://www.joonweb.com/partners). 2. **Development Store / Site**: You have created at least one **Development Site** (*Informative* or *eCommerce*) in your Partner dashboard for testing. 3. **JoonWeb CLI**: Install the official CLI globally on your system: ```bash npm install -g @joonweb/cli ``` 4. **Web Browser**: Latest version of **Google Chrome** or **Mozilla Firefox** for OAuth consent and embedded iframe testing.

Step 1: Initialize Your App (joonweb app init) #

To scaffold a new ready-to-run application: 1. Open your **terminal** or command prompt. 2. Navigate to your workspace folder where you want to create your project. 3. Run the initialization command: ```bash joonweb app init ``` *(Alias: `joonweb app create`)* ### Interactive CLI Setup Flow: - **Authentication**: If you are not logged in, the CLI automatically opens your browser to complete Partner authentication. - **Select Account**: Choose your **JoonWeb Partner Account**. - **App Action**: Select **Create a New JoonWeb App**. - **Tech Stack**: Select your preferred technology stack (PHP App, Node.js Express, or React). - **App Details**: Enter your **App Name** and confirm the auto-generated app slug. Once finalized, the CLI scaffolds your project folder with all required SDK files and configuration manifests.

Step 2: Understand the App Manifest (joonweb.app.json) #

During initialization, the CLI generates a central manifest file: `joonweb.app.json` inside your project root. > ⚠️ **CRITICAL WARNING**: `joonweb.app.json` contains your app credentials, client ID, client secret, OAuth scopes, and proxy configuration. **It MUST NOT be deleted, replaced, or copied from another project at any cost.** ```json { "appId": "8c21b0e81773747658577", "name": "mytestapp", "client_id": "0b990a0bb51fb125", "client_secret": "b90984d32211c49f8b94a3e04eb588f3be42", "app_url": "https://mytestapp.joonweb.app", "redirect_uri": "https://mytestapp.joonweb.app/auth/callback", "scopes": "read_products,write_products", "proxy": { "url": "https://mytestapp.joonweb.app/proxy", "status": "active" }, "webhooks": [ { "event": "products/create", "address": "https://mytestapp.joonweb.app/webhooks/products_create", "format": "json" } ], "template": "php", "embedded": true, "platform": "ecommerce", "version": "1.0.0" } ``` For a full breakdown of each field, visit the [App Manifest Reference Guide](/apps/dev-tools/app-manifest).

Step 3: Run Your App in Development Mode (joonweb app serve) #

To test your app live inside the JoonWeb Admin iframe: 1. Open terminal inside your app project directory. 2. Run the development server: ```bash joonweb app serve ``` *(Alias: `joonweb app dev`)* ### What happens when you run `joonweb app serve`: - The CLI starts your local backend server. - Establishes a secure **HTTPS Cloudflare Tunnel**. - Opens your browser to select your **Development Store**. - Redirects to the OAuth authorization page. After merchant approval, your app loads seamlessly embedded inside the JoonWeb Admin dashboard.

Step 4: Required App Architecture Components #

All production-grade JoonWeb apps must correctly implement the following 3 core components: 1. **SessionStorage**: Manages secure session tokens and merchant store credentials. 2. **JoonWeb API**: Server-side API communication using official SDKs ([`@joonweb/joonweb-sdk`](/admin-api/overview/authorization) or [`joonweb/joonweb-sdk`](/admin-api/overview/authorization)). 3. **App Bridge**: Client-side UI bridge connecting your embedded app with the JoonWeb Admin dashboard ([`App Bridge Guide`](/apps/app-bridge/app-bridge-overview)).

🎨 Extending Your App with Storefront Extensions #

If your app needs native Storefront UI components (Sections, App Blocks, or Embed Scripts) that merchants can customize in the Site Builder, do **not** build them inside your main backend app. Instead, use the CLI to generate a Theme App Extension. Learn how in our dedicated tutorial: 👉 **[Create Theme App Extensions Guide](/apps/theme-app-extensions/create-theme-app-extensions)** — Step-by-step walkthrough for `.jw` files and JSON rules schema.

Step 5: Deploy & Release Your App (joonweb app deploy) #

### Deploying Your App Snapshot When you are ready to publish code updates, run: ```bash joonweb app deploy ``` *(Alias: `joonweb app push`)* This command will: - Bundle your application code. - Create a new **App Version**. - Save it as a **draft build**. - Prompt if you want to release the version live. ### Releasing a Version Live If you choose to release the version, the update becomes immediately active for all store merchants who installed your app. ### Marketplace Distribution Deploying code does **not** automatically publish your app to the public marketplace. To make your app public: 1. Log into your [JoonWeb Partner Dashboard](https://www.joonweb.com/partners). 2. Navigate to **App Distribution**. 3. Complete listing details, screenshots, and submit for **App Review**. 4. Upon approval, your app will be listed in the **JoonWeb App Marketplace**.

Step 6: Common Errors & Troubleshooting #

### Port Already Open (`ERR: already port open`) If you encounter a port lock error when running `joonweb app serve`: ```bash joonweb refresh ``` Running `joonweb refresh` terminates leftover background server processes and clears port `11014` locks. ### Deployment Failed If deployment fails: 1. Verify `joonweb.app.json` credentials and scopes are valid. 2. Ensure all required dependencies are installed. 3. Check terminal logs for detailed error trace and re-deploy.

Development Workflow Summary #

Basic workflow for building a JoonWeb app: 1. **Initialize App**: `joonweb app init` 2. **Start Dev Server**: `joonweb app serve` 3. **Build Features & API Calls**: Use Admin API & App Bridge 4. **Add Extensions** *(Optional)*: Refer to [Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions) 5. **Deploy Snapshot**: `joonweb app deploy` 6. **Publish App**: Partner Dashboard Review

What's Next? #

- ⚙️ **[App Manifest Reference (joonweb.app.json)](/apps/dev-tools/app-manifest)** — Configure app webhooks, scopes, and app proxy. - 🎨 **[Create Theme App Extensions](/apps/theme-app-extensions/create-theme-app-extensions)** — Build native `.jw` storefront blocks. - 🌉 **[App Bridge Component Guide](/apps/app-bridge/app-bridge-overview)** — Learn native UI modals & client-side routing. - 🔑 **[Admin API Authorization](/admin-api/overview/authorization)** — OAuth token exchange and session verification. - 🛠️ **[JoonWeb CLI Command Reference](/apps/dev-tools/cli-commands)** — View all CLI options.