For a better reading experience, please visit Codelabs. (opens in a new tab)

Set up environment

Prerequisites

• Before building a miniapp, get your Node.js environment ready. Go to the Node.js (opens in a new tab) website and download the installer.

Install editor

Before you develop a panel miniapp, download and install the following recommended editors as needed:

• Visual Studio Code (recommended): supports common built-in features, such as formatting and navigation. This editor is subject to a high level of community engagement.
• WebStorm: Highly integrated IDE.
• Sublime Text: a lightweight editor.

Install app

If you want to install a specific app version, you can submit a ticket (opens in a new tab) on the Tuya Developer Platform to request further support.

iOS:

Go to App Store > Smart Life (opens in a new tab), or search for Smart Life on App Store for iPhones, and download the app.

Android:

Go to Google Play > Smart Life (opens in a new tab), or search for Smart Life on app stores for Android, and download the app.

Install Tuya MiniApp IDE

Tuya MiniApp IDE can be used to create your miniapp project, and develop, debug, and upload the miniapp.

Go to Tuya MiniApp IDE and download the latest version.

Install NVM

Node.js version manager (NVM) helps you manage multiple Node.js versions. If this is your first installation, set up the environment variable as per the instruction.

1. Open the Terminal.

2. Install the NVM (opens in a new tab).

   	curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash

3. Enter nvm -v to confirm that NVM is installed as expected. If a version number is returned, the installation is successful. Make sure you are using Node.js v16.0.0 or later. If the error nvm: command not found is returned, follow the instructions in FAQs to fix the error.

4. Enter nvm install 16.20.2 to install Node.js v16.20.2.

5. (Optional) Run the command nvm use to switch among Node.js versions. We recommend that you install Node.js v16.20.2 or later.

   	nvm use 16.20.2

Install Yarn

If you have installed Yarn, or used Node.js Package Manager (npm), performant npm (pnpm), or other dependency manager tools, you can skip this section.

1. Open the Terminal.

2. Enter npm install -g yarn to install Yarn.

3. Enter yarn -v to confirm that Yarn is installed as expected.

Create product

Concepts

A control panel runs on an app and represents a product that is an abstraction of a smart device. Before you create a product, you can learn about the relationship between control panels, products, and devices.

1. A control panel is a graphical user interface (GUI) application that can run on the Smart Life app and Tuya-enabled OEM apps to control smart devices and display real-time device status.
2. A product links a control panel with a smart device. A product describes the name, features, and data points (DPs) of the smart device displayed on the app.
3. A smart device is embedded with a network module provided by Tuya. The device is labeled with a QR code. Users can scan the QR code with the Smart Life app, and get and install the control panel of the device on the app.
4. The following figure shows the relationship between control panels, products, and smart devices.

Preview

Procedure

A product defines the DPs of the associated panel and device. Before you develop a panel, you must create a product, defines the required DPs, and then implement these DPs on the panel.

The steps to create a product on the Tuya Developer Platform:

1. Register and log in to the Tuya Developer Platform (opens in a new tab).

2. In the left navigation pane, choose Product > Development (opens in a new tab) and then click Create. Suppose you want to create a home appliance product. Select Standard Category > Large Home Appliance > Air Conditioner.

   

   Preview

3. Enter a product name, keep other default options, and then click Create.

4. After the product is created, go to the development page of the smart product and enter the Function Definition step. Click Add in the Standard Functions section to see a list of available standard functions. Click Select All > OK to have standard functions configured for the product.

   

   Preview

• For more information about how to create a product, see Create Products (opens in a new tab).
• For more information about product functions, see Product Functions (opens in a new tab).

Initialize project

Prerequisites

You must register an account with the Tuya Developer Platform and use this account to log in to the Tuya MiniApp Developer Platform before you can create a miniapp. If you do not have an account, register now (opens in a new tab).

Create panel miniapp

1. Log in to the Tuya MiniApp Developer Platform (opens in a new tab) to see the page that lists existing miniapps.

2. Click Create on this page.

3. Set the name, logo, type, and other required information about the miniapp, and click OK. Miniapp Type must be set to Panel Miniapp.

   

   Preview

Initialize project

1. Open Tuya MiniApp IDE, log in to it with the account of the Tuya Developer Platform, and then create a miniapp project.

2. Set the following information as instructed, click OK, and then proceed to select a project template.

   • Project Path: the directory in which the project will be located.

   • Project Name: the name of the project.

   • Link MiniApp: Select the miniapp created on the Tuya MiniApp Developer Platform.

     The account logged in to Tuya MiniApp IDE must have developer permissions granted in the Tuya MiniApp Developer Platform and be associated with the miniapp. This allows the account to develop, debug, and upload the code with Tuya MiniApp IDE.

   • Link Product: the product to be linked with the current panel miniapp. This is the product created in the Create Product step in this quick start guide.

     

     Preview

3. Based on your panel miniapp development needs, select the appropriate preset template, and then click Create. Specific instructions are as follows:

   • When you hover over a template, the corresponding template QR code will be displayed, which you can scan to experience.

   • Clicking "Source" will automatically redirect to the corresponding GitHub repository (if available).

   • Clicking "Guide" will automatically redirect to the corresponding Codelabs tutorial (if available).

   Category templates usually include specific product feature point requirements. If you need to use them, make sure these feature points are defined. If there is no suitable category template, it is recommended to use the Public SDM Template.

   

   Preview

4. Then, you are automatically navigated to the miniapp development and debugging window. Now, your project is initialized.

   

   Preview

Develop and debug

Start project

Navigate to the project directory. Tuya MiniApp IDE will automatically install dependencies and start the panel miniapp.

After the project is imported, if Tuya MiniApp IDE does not automatically install dependencies and start the panel miniapp, check if the parameter devMode: ray exists in project.tuya.json.

{
  "devMode": "ray"
}

Enable panel tools

After a project is started, your program is automatically compiled in real time. However, a live preview of the UI layout is unavailable on Tuya MiniApp IDE.

This is because the operation of the panel miniapp relies on a corresponding virtual device, so we need to enable the panel tool first.

1. In the top right corner of Tuya MiniApp IDE, click Account to show a QR code. Open the Smart Life app and scan the QR code to grant your account access to the miniapp.

   

   Preview

2. Click Plugins > Panel Tools at the top of Tuya MiniApp IDE to display the list of devices. The panel tools support three debugging modes: debug virtual device, debug real device, and debug device group.

   

   Preview

Debug virtual device

Choose the device you want to debug from the list of devices labeled as Virtual Device. If no virtual device is available, click Add virtual devices in the top right corner to add one.

Preview

Use the Smart Life app to scan the code. The following screen will appear, with the panel miniapp reloaded. You can proceed to develop your panel miniapp.

Note that after you scan the QR code, the default panel associated with the current product will open instead of the miniapp being developed. To debug the miniapp on the app, see the Remote Debugger section.

Preview

Debug real device

If you have added a real device to the app, it will appear in the list of devices labeled as Real Device. Choose a device to open the debugging interface. If no real device is available, add one using the Smart Life app. The plugin supports protocols including Wi-Fi, Zigbee, Mesh, Bluetooth mesh, and Beacon, as well as TuyaLink-based devices.

Preview

Debug device group

If you have created a device group on the app, it will appear in the list of devices labeled as Group. Choose a group to open the debugging interface.

Differences in three debugging modes

• Virtual devices can simulate status reporting after receiving commands from the control panel, but this feature does not apply to real devices or groups.
• Virtual devices can be unbound from the plugin and added to another account, but this feature does not apply to real devices or groups.
• Virtual devices can simulate status reporting in online status, but this feature does not apply to real devices or groups.

Remote debugger

If the real app environment is not required in your current development stage, you can skip this section.

The built-in plugin in Tuya MiniApp IDE is v1.4.0. If you are using the plugin v1.4.0 or later, you can open the debugging interface by clicking the third button in the menu bar without specifying any parameters. There is also no need to modify the deviceId or groupId parameter. However, this does not apply to devices that support Bluetooth only.

Preview

Debug development and trial versions

You can enable the debug mode on the app and then tap the vConsole button on the panel interface to view logs for troubleshooting.

Call changeDebugMode can enable the app's debug mode. Please be careful not to enable it in the production environment.

Preview

Preview

Test miniapp

Upload program

Click Upload in the top right corner of Tuya MiniApp IDE, enter the version number and remarks, and then upload the local program to the cloud.

Preview

Complete required information

1. After the program is uploaded, make sure the current panel miniapp has basic information and settings configured. For this purpose, go to the Tuya MiniApp Developer Platform (opens in a new tab) and tap the target miniapp on the list.

2. Go to Basic Settings, set Miniapp Logo, Miniapp Name, and other basic information, and enter the display names and preview images, respectively in Chinese and English, to be displayed on the Tuya Developer Platform.

   

   Preview

Set as trial version

1. Go to Versions and find the uploaded version.

2. Click Set as Trial Version and then OK. The Trial QR code button will appear. Before you scan the QR code, set the allowlist first.

   

   Preview

Add test account to allowlist

Go to Allowlist and click Add. In the dialog box that appears, select the target app, set the app account and remarks, and then click OK.

Preview

Scan to test miniapp

1. Go to Versions, find the trial version, and then click Trial QR Code.

2. Get the required device ID, and enter it in the QR Code of Trial Version dialog box that appears. Note that you need to choose between a virtual device ID and a real device ID and enter the required device ID.

   The device ID can be obtained through the device information section in the panel tool.

3. Use the allowlisted account of the Smart Life app to scan the QR code to start testing. Note that the virtual device or real device must exist in the home that is managed on the current app before you can access the device panel.

Submit for review and release

Submit for review

1. Log in to the Tuya MiniApp Developer Platform (opens in a new tab) and click the target miniapp to go to Versions.

2. On the Dev Version tab, find the target version and click Submit for Review.

Release approved version

1. This version is moved to the Review Version tab and appears with the review status.

2. The approved version is moved to the Official Version tab. You can click Start Service to make this version available to users, or click Pause Service to make it unavailable to users.

Link product

1. After the official version is available to users, go to the Tuya Developer Platform (opens in a new tab).

2. Find the product to be linked with the miniapp, go to the Device Interaction step of product development, and then click Change Panel.

   

   Preview

3. Select Self-Developed Panel to find the newly-released panel miniapp. Hover over the panel miniapp and click Select.

   

   Preview

Perform regression test

1. On the Tuya Developer Platform, go to the Device Interaction step of product development, use the Smart Life app to scan the QR code, and then add the virtual device.

2. Now, the app account outside the allowlist can access the virtual device of the product or the real device paired with the app. Then, the newly-released panel miniapp will appear for device control.

FAQs

Why does the error nvm: command not found occur after entering nvm -v?

The possible reason is that the path where NVM is located is not specified as an environment variable. You can perform the following steps and set the environment variable:

1. Open the Terminal.

2. Enter cd ~ to go to the Home directory of the current account.

3. Run the following command to open the configuration file.

   • Windows

     open .bash_profile

   • macOS

     open .bashrc

4. Copy and paste the following code block to the configuration file and save the file.

   export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

5. Enter source .bash_profile or source .bashrc to reload the configuration file.

6. Enter nvm -v to view the NVM version and check whether the installation is successful.

For more information, see NVM#Additional Notes (opens in a new tab).

What are the differences between Tuya MiniApp IDE debugging and remote debugger?

Tuya MiniApp IDE-based debugging relies on a virtual device generated with the dedicated plugin. Basic hardware and device capabilities required by the panel miniapp are preset in the virtual device. This allows you to quickly design the UI layout in Tuya MiniApp IDE. However, you cannot access all hardware or device capabilities available on the app, for example, QR code scanning, phone calls, and device connection. You can use these two debugging methods according to your needs.

1. Tuya MiniApp IDE-based debugging: During the initial development stage, this debugging method helps you quickly build the UI layout and implement basic functional logic.
2. Remote debugger: During the medium and later development stages, after basic functional logic is finished, this debugging method helps you test the capabilities available on the app.

How can I fix the issue of the app not supporting the miniapp?

The app does not support the base library or Kit package that the miniapp depends on. See API Overview and check for version compatibility.