Zalo Mini App CLI

Common errors

• zmp: command not found

  cause The Zalo Mini App CLI (zmp-cli) is not installed globally or is not in your system's PATH.
  fix Run `npm install -g zmp-cli` to install it globally. If it's already installed, ensure your `npm` global binaries directory is in your system's PATH environment variable, or try `npx zmp <command>`.

• Login failed: Invalid Access Token

  cause The provided access token is expired, revoked, or incorrect, preventing authentication with the Zalo developer platform.
  fix Obtain a fresh access token from the Zalo for Developers portal (Công cụ > API Explorer > Lấy Access Token) and ensure it's for the correct Zalo App. Re-run `zmp login` or pass the new token explicitly if using programmatic authentication.

• Error: Zalo Mini App ID is required

  cause During project initialization or deployment, a valid Zalo Mini App ID was not provided or configured.
  fix Ensure you have registered your Mini App on mini.zalo.me/developers and have obtained an App ID. When prompted by `zmp init` or `zmp deploy`, provide the correct Zalo Mini App ID.

• Project requires Vite 2.x for Device mode. Webpack projects are not compatible.

  cause When attempting to run `zmp start -D` (Device mode), the CLI detected that the project is using Webpack instead of Vite 2.x or newer.
  fix To use Device mode, your Zalo Mini App project must be configured with Vite 2.x. Consider migrating your project build system to Vite or use the standard `zmp start` command for browser preview mode instead.

Warnings

• breaking Major version updates (e.g., from v3 to v4) for `zmp-cli` may introduce breaking changes in command-line arguments, options, or output formats. Always consult the official release notes before upgrading in CI/CD environments or scripts.
  Fix: Review the official Zalo Mini App documentation for version-specific changes. Update CI/CD scripts and local development workflows to reflect new command syntaxes or expected outputs.
• gotcha Authentication methods for `zmp login` include QR code scanning via the Zalo mobile app or providing an access token. QR codes have a limited lifespan, and access tokens can expire. Ensure tokens are fresh or be prepared to re-authenticate frequently.
  Fix: For automation, prefer using an `access token` provided as an environment variable or command argument, and implement a token refresh mechanism if supported. For manual login, ensure quick access to your Zalo mobile app for QR scanning.
• gotcha While `npm install -g zmp-cli` provides a global `zmp` command, you might encounter issues with different Node.js versions or permissions. Alternatively, using `npx zmp` will execute the latest version without global installation, or execute a locally installed version.
  Fix: If experiencing global command issues, try `npx zmp <command>` to ensure you're running a consistent version. For project-specific needs, install `zmp-cli` as a dev dependency (`npm install --save-dev zmp-cli`) and add scripts to your `package.json` like `"deploy": "npx zmp deploy"`.
• gotcha When initializing a new project with `zmp init`, the CLI offers two modes: 'Create a new ZMP project' which generates a new directory, or 'Use ZMP to deploy only' which modifies the current working directory. Misunderstanding this choice can lead to unexpected file creation or overwrites.
  Fix: Always execute `zmp init` in a clean or intended directory. Carefully read the prompts and select the correct option to avoid unintended modifications to your existing codebase or directory structure. Back up important files before running `init` in 'deploy only' mode on an existing project.

Install

• npm install zmp-cli npm
• yarn add zmp-cli yarn
• pnpm add zmp-cli pnpm

Imports

• login
  wrong:

  import login from 'zmp-cli'; // 'login' is a named export, not default.

  correct:

  import { login } from 'zmp-cli';

  The `login` function initiates the Zalo Mini App developer authentication process, either via QR code or access token. It returns a Promise<void>.
• init
  wrong:

  const { init } = require('zmp-cli'); // Primarily ESM; CJS might have issues or require transpilation.

  correct:

  import { init } from 'zmp-cli';

  The `init` function allows programmatic creation or conversion of a Zalo Mini App project. It accepts an optional `InitOptions` object and returns a Promise<void>.
• deploy
  wrong:

  import * as zmp from 'zmp-cli'; zmp.deploy(); // While technically correct, direct named import is preferred.

  correct:

  import { deploy } from 'zmp-cli';

  The `deploy` function handles the deployment of a Zalo Mini App. It accepts an optional `DeployOptions` object and returns a Promise<void>.

Quickstart

Demonstrates global CLI installation and common shell commands for login and project initialization, alongside a conceptual programmatic invocation example using the exposed `login` function.

import { login, init } from 'zmp-cli';
import { exec } from 'child_process';

// --- CLI Usage ---
console.log('--- CLI Usage ---');
exec('npm install -g zmp-cli', (err, stdout, stderr) => {
  if (err) {
    console.error(`CLI install error: ${stderr}`);
    return;
  }
  console.log('Zalo Mini App CLI installed globally.');

  exec('zmp --help', (err, stdout, stderr) => {
    if (err) {
      console.error(`zmp --help error: ${stderr}`);
      return;
    }
    console.log('zmp --help output:\n', stdout.substring(0, 200) + '...');

    console.log('\nRun `zmp login` to authenticate or `zmp init` to create a project.');
    console.log('For example: `zmp login` will prompt for QR code or access token.');
    console.log('Or: `zmp init` will guide through project creation.');

    // --- Programmatic Usage (Conceptual) ---
    console.log('\n--- Programmatic Usage (Conceptual) ---');
    async function automateZmp() {
      try {
        console.log('Attempting programmatic login (this will likely open a browser/terminal prompt).');
        // In a real scenario, you might pass an access token directly if the API supports it.
        // For now, this acts as an example of calling the exported function.
        await login();
        console.log('Login initiated programmatically. Please complete in browser/terminal.');

        console.log('Initiating a new Zalo Mini App project programmatically (e.g., in a temp directory).');
        // For actual programmatic init, you'd provide options like project name, template, etc.
        // await init({ name: 'my-automated-app', template: 'blank', appId: process.env.ZMP_APP_ID ?? '' });
        console.log('`init()` function would be called here with specific options.');
      } catch (error) {
        console.error('Programmatic ZMP operation failed:', error);
      }
    }
    // automateZmp(); // Uncomment to run the programmatic example
  });
});