{"id":12708,"library":"zmp-cli","title":"Zalo Mini App CLI","description":"The `zmp-cli` is a command-line interface utility designed to streamline the development, testing, and deployment of Zalo Mini Apps. It provides essential commands for developer login, project creation, building, previewing, and deployment, offering an alternative to the Zalo Mini App Extension. Currently at version 4.0.3, the package was last published a month ago as of March 2026, indicating active maintenance. It focuses on integrating into various IDEs and CI/CD pipelines for automation. Key differentiators include its ability to convert existing web applications into Zalo Mini Apps and its support for both QR code and access token-based authentication. Its primary mode of interaction is through shell commands, though it also exposes a programmatic interface for advanced automation in JavaScript/TypeScript environments.","status":"active","version":"4.0.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install zmp-cli","lang":"bash","label":"npm"},{"cmd":"yarn add zmp-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add zmp-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `login` function initiates the Zalo Mini App developer authentication process, either via QR code or access token. It returns a Promise<void>.","wrong":"import login from 'zmp-cli'; // 'login' is a named export, not default.","symbol":"login","correct":"import { login } from 'zmp-cli';"},{"note":"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>.","wrong":"const { init } = require('zmp-cli'); // Primarily ESM; CJS might have issues or require transpilation.","symbol":"init","correct":"import { init } from 'zmp-cli';"},{"note":"The `deploy` function handles the deployment of a Zalo Mini App. It accepts an optional `DeployOptions` object and returns a Promise<void>.","wrong":"import * as zmp from 'zmp-cli'; zmp.deploy(); // While technically correct, direct named import is preferred.","symbol":"deploy","correct":"import { deploy } from 'zmp-cli';"}],"quickstart":{"code":"import { login, init } from 'zmp-cli';\nimport { exec } from 'child_process';\n\n// --- CLI Usage ---\nconsole.log('--- CLI Usage ---');\nexec('npm install -g zmp-cli', (err, stdout, stderr) => {\n  if (err) {\n    console.error(`CLI install error: ${stderr}`);\n    return;\n  }\n  console.log('Zalo Mini App CLI installed globally.');\n\n  exec('zmp --help', (err, stdout, stderr) => {\n    if (err) {\n      console.error(`zmp --help error: ${stderr}`);\n      return;\n    }\n    console.log('zmp --help output:\\n', stdout.substring(0, 200) + '...');\n\n    console.log('\\nRun `zmp login` to authenticate or `zmp init` to create a project.');\n    console.log('For example: `zmp login` will prompt for QR code or access token.');\n    console.log('Or: `zmp init` will guide through project creation.');\n\n    // --- Programmatic Usage (Conceptual) ---\n    console.log('\\n--- Programmatic Usage (Conceptual) ---');\n    async function automateZmp() {\n      try {\n        console.log('Attempting programmatic login (this will likely open a browser/terminal prompt).');\n        // In a real scenario, you might pass an access token directly if the API supports it.\n        // For now, this acts as an example of calling the exported function.\n        await login();\n        console.log('Login initiated programmatically. Please complete in browser/terminal.');\n\n        console.log('Initiating a new Zalo Mini App project programmatically (e.g., in a temp directory).');\n        // For actual programmatic init, you'd provide options like project name, template, etc.\n        // await init({ name: 'my-automated-app', template: 'blank', appId: process.env.ZMP_APP_ID ?? '' });\n        console.log('`init()` function would be called here with specific options.');\n      } catch (error) {\n        console.error('Programmatic ZMP operation failed:', error);\n      }\n    }\n    // automateZmp(); // Uncomment to run the programmatic example\n  });\n});","lang":"typescript","description":"Demonstrates global CLI installation and common shell commands for login and project initialization, alongside a conceptual programmatic invocation example using the exposed `login` function."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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\"`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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>`.","cause":"The Zalo Mini App CLI (zmp-cli) is not installed globally or is not in your system's PATH.","error":"zmp: command not found"},{"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.","cause":"The provided access token is expired, revoked, or incorrect, preventing authentication with the Zalo developer platform.","error":"Login failed: Invalid Access Token"},{"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.","cause":"During project initialization or deployment, a valid Zalo Mini App ID was not provided or configured.","error":"Error: Zalo Mini App ID is required"},{"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.","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.","error":"Project requires Vite 2.x for Device mode. Webpack projects are not compatible."}],"ecosystem":"npm"}