English | 简体中文

@tcsas-team/tcsas-miniprogram-ci

@tcsas-team/tcsas-miniprogram-ci is a Node.js tool for automating the upload, preview, and dependency building of TCSAS Mini Programs. It can be used both as a command-line (CLI) tool and as an NPM package in your project.

✨ Features

• Upload Mini Program: Uploads code, corresponding to the "Upload" function in the Mini Program DevTools.
• Preview Mini Program: Generates a preview QR code for on-device debugging, corresponding to the "Preview" function in the DevTools.
• NPM Build: Automatically builds npm dependencies, corresponding to "Tools -> Build NPM" in the DevTools.
• Detailed Progress: Provides an onProgressUpdate callback to track task status in real-time.

📦 Installation

Global Installation (for CLI usage)

If you want to use the tcsas-miniprogram-ci command from anywhere, install it globally:

npm install -g @tcsas-team/tcsas-miniprogram-ci

Local Installation (for project usage)

If you want to use it within your Node.js project via require, install it locally:

npm install @tcsas-team/tcsas-miniprogram-ci

🔑 Quick Start: Choose Your Deployment Model

This tool supports both SaaS and Private Deployment models. Please follow the guide corresponding to your environment.

SaaS Mode Usage Guide: Obtaining the Key File

Step 1: Obtain API Keys from Tencent Cloud Console

1. Account Creation

   • Navigate to the Tencent Cloud Access Management page.

     1. Log in to the Tencent Cloud Console with the main account, go to the Tencent Cloud Access Management page, enter the user list, and click "Create User".

   • Create User

     1. Click "Create Quickly", fill in the username and security settings as needed (or leave as default). The "Select Tag" option can be ignored.

   • Copy User Login Information

     1. After successful creation, you will be redirected to the user information page. Click "Copy" to copy the user's login credentials.

2. User Permission Settings

   • Go to the user details page.

     1. Return to the user list and click on the newly created user to enter their details page.

   • Quickly Configure Permissions via Preset Policies

     1. Click the "Permissions" tab, then click "Add Policy".
     2. Click the "Select a policy to associate from the Policy List" tab. In the search box, enter QcloudTCSASMiniProgramSeniorDeveloperAccess or QcloudTCSASMiniProgramDeveloperAccess to find the TCSAS Mini Program Senior Developer or Developer access policies. Select the appropriate one and click "Next".
     3. Confirm the permissions and click "OK".

3. OpenAPI Key Generation

   • Go to the user details page.

     1. Return to the user list and click on the user to enter their details page.

   • Create Key

     1. Click the "API Key" tab, then click the "Create Key" button.

   • Download Key

     1. A dialog will pop up with the key information. You must download the key now, as it cannot be viewed again after the dialog is closed.

     Note: It is crucial to download the .csv file rather than manually copying the SecretId and SecretKey.

Step 2: Upload to TCSAS Console and Generate the Final Key

1. Log in to the TCSAS Console.
2. Navigate to the "Team Management - CI/CD" menu.
3. Upload the .csv key file you downloaded from Tencent Cloud in Step 1.
4. TCSAS will validate your key, bind it with platform information, and then automatically download an encrypted .private.key file.

✅ The .private.key file you should use for the privateKeyPath parameter is the one downloaded in this second step.

Private Deployment Usage Guide: Obtaining the Key File

The private deployment model uses a dedicated key file downloaded directly from the TCSAS console.

Step 1: Platform Administrator Creates and Authorizes the Key Pair

1. Log in to the TCSAS console with a TCSAS Platform Administrator account.
2. Navigate to the "Platform Management - OpenAPI Management" menu and switch to the "Secret key Management" tab.
3. Click "Create Key Pair" to generate a key for CI/CD. Note: do not enable the "Key rotation mechanism".
4. During creation, you must check all required OpenAPI permissions, such as:
   • FileUpload
   • CreateMNPVersion / CreateMNGVersion
   • DescribeMNPVersion / DescribeMNGVersion
   • CreateMNPSecretKey
5. After generation, download and securely store the platform-level .csv key file.

Step 2: Mini Program Team Administrator Uploads and Downloads the Final Key

1. Log in to the TCSAS console with a Mini Program Team Administrator account.
2. Navigate to the "Team Management - CI/CD" menu.
3. Upload the platform-level key file downloaded in Step 1.
4. Upon successful upload, a new key tied to the team's Mini Program will be generated and a .key file will be downloaded automatically.

✅ The key file you should use for the privateKeyPath parameter is the one downloaded in this second step.

🚀 Usage Guide

This tool supports two main usage methods: as an NPM package in your code, or as a CLI from the command line.

1. As an NPM Package

In your Node.js script, you first need to import the package and instantiate a Project object.

a. Initialize Project

All operations require a Project instance.

const ci = require('@tcsas-team/tcsas-miniprogram-ci');

// Note: When calling new ci.Project, ensure the project code is complete to avoid file-not-found errors during compilation.
const project = new ci.Project({
  appid: 'wxsomeappid',
  type: 'miniProgram',
  projectPath: 'your/project/path',
  privateKeyPath: 'your/path/to/privatekey',
});

Project constructor parameters:

| Parameter | Type | Required | Description | | ---------------- | ---------- | -------- | --------------------------------------------------------------------------- | | appid | string | Yes | The AppID of your Mini Program. | | projectPath | string | Yes | The root directory path of your Mini Program project. | | privateKeyPath | string | No | The file path to the code upload private key. Use this or privateKey. | | privateKey | string | No | The text content of the private key. Use this or privateKeyPath. | | type | string | No | The project type, either 'miniProgram' (default) or 'miniGame'.

b. Upload Code ci.upload()

Uploads the project code.

(async () => {
  const uploadResult = await ci.upload({
    project,
    version: '1.0.1',
    desc: 'hello',
    onProgressUpdate: (info) => console.log(info),
  });
  console.log(uploadResult);
})();

upload function parameters:

| Parameter | Type | Required | Description | | ------------------ | ---------- | -------- | --------------------------------------------------------------------------- | | project | Project | Yes | An instance of the Project created via new ci.Project(). | | version | string | Yes | The version number for this upload, e.g., '1.0.1'. | desc | string | No | The description for the version. | | onProgressUpdate | Function | No | A callback for progress updates. See Progress Update Callback. |

Return Value

The function returns a Promise that resolves to an object containing package information:

| Property | Type | Description | | ---------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | subPackageInfo | Array<Object> | Package information. Each object contains:name (string): Package name (__FULL__ for the entire project, __APP__ for the main package, or subpackage name).size (number): Package size in bytes. |

c. Preview Code ci.preview()

Generates a preview QR code.

(async () => {
  const previewResult = await ci.preview({
    project,
    desc: 'hello',
    onProgressUpdate: console.log,
    qrcodeFormat: 'image',
    qrcodeOutputDest: './preview-qrcode.jpg',
    pagePath: 'pages/index/index',
    searchQuery: 'from=test',
  });
  console.log(previewResult);
})();

preview function parameters:

| Parameter | Type | Required (when...) | Description | | ----------------------- | --------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | | project | Project | Yes | An instance of the Project created via new ci.Project(). | | desc | string | No | The description for the preview version. | | onProgressUpdate | Function| No | A callback function for progress updates. | | qrcodeFormat | string | No | QR code format: 'terminal' (default), 'image', or 'base64'. | qrcodeOutputDest | string | Yes (qrcodeFormat is image or base64) | The file path to save the QR code. | | pagePath | string | No | The specific page path to open upon scanning the QR code. | | searchQuery | string | No | Launch query for the preview page, e.g., 'a=1&b=2'. | bigPackageSizeSupport | boolean | No | For previews, enable subpackage size optimization. Increases subpackage/main package limit to 4MB (8MB for games). |

Return Value

The function returns a Promise that resolves to an object with preview information:

| Property | Type | Description | | ---------------- | --------------- | -------------------------------------------------------------------------------------------------------- | | subPackageInfo | Array<Object> | Package size information, same structure as the upload function's return value. | | expireTime | number | A timestamp indicating when the QR code will expire. |

d. NPM Build

ci.packNpm(project, options): Executes npm build inside the project's configured miniprogramRoot.

await ci.packNpm(project, {
  reporter: (infos) => { console.log(infos) }
});

ci.packNpmManually(options): Manually specifies a package.json path and an output directory to perform an npm build.

Example: Building from a custom node_modules location

In some scenarios, the node_modules to be built might be located outside the Mini Program project. packNpmManually is designed for this need. For example, consider the following project structure:

.
├── lib                # Directory containing node_modules and package.json
│   ├── node_modules
│   └── package.json
└── miniprogram-project # The Mini Program project directory
    └── miniprogram      # The desired final output directory for miniprogram_npm

You can use the following code to perform the build and move the artifacts:

await ci.packNpmManually({
  packageJsonPath: './lib/package.json',
  miniprogramNpmDistDir: './miniprogram-project/miniprogram/',
});

After execution, the final project structure will be:

.
├── lib
│   ├── node_modules
│   └── package.json
└── miniprogram-project
    └── miniprogram
        ├── app.js
        ├── ...
        └── miniprogram_npm  # <--- The build artifact is moved here
            └── ...

packNpmManually function parameters:

| Parameter | Type | Required | Description | | ----------------------- | -------- | -------- | --------------------------------------------------------------------------- | | packageJsonPath | string | Yes | The path to the package.json corresponding to the node_modules to be built. | | miniprogramNpmDistDir | string | Yes | The final output directory for the miniprogram_npm build artifact. |

2. As a CLI

Use the tcsas-miniprogram-ci command with subcommands (upload or preview) in your terminal.

a. upload command

tcsas-miniprogram-ci upload \
  --project-path ./demo-proj/ \
  --private-key-path ./private.key \
  --appid YOUR_APPID \
  --upload-version 1.0.1 \
  --upload-desc "hello"

upload command parameters:

| Parameter | Alias | Required | Description | | -------------------- | ------- | -------- | --------------------------- | | --project-path | --pp | Yes | Path to the Mini Program project. | | --private-key-path | --pkp | Yes | Path to the key file. | | --appid | | Yes | The Mini Program's AppID. | | --upload-version | --uv | Yes | The version to upload. | | --upload-desc | --ud | No | The version description. |

b. preview command

tcsas-miniprogram-ci preview \
  --project-path ./demo-proj/ \
  --private-key-path ./private.key \
  --appid YOUR_APPID \
  --qrcode-format image \
  --qrcode-output-dest '/tmp/qrcode.jpg'

preview command parameters:

| Parameter | Alias | Required | Description | | ---------------------- | ------- | -------- | ---------------------------------------------- | | --project-path | --pp | Yes | Path to the Mini Program project. | | --private-key-path | --pkp | Yes | Path to the key file. | | --appid | | Yes | The Mini Program's AppID. | | --qrcode-format | | No | QR code format, can be 'terminal', 'image'. | --qrcode-output-dest | | No | Path to save the QR code image. |

c. pack-npm and pack-npm-manually commands

# Build inside the project
tcsas-miniprogram-ci pack-npm --project-path ./YOUR_PROJECT/

# Build manually
tcsas-miniprogram-ci pack-npm-manually \
  --pack-npm-manually-package-json-path PACKAGE_JSON_PATH \
  --pack-npm-manually-miniprogram-npm-dist-dir DIST_PATH

⚙️ Progress Update Callback (onProgressUpdate)

onProgressUpdate is a function that receives status updates during the tool's execution. It receives an object with the following format:

{ message: string, status: 'doing' | 'done' }

• message: A description of the current status.
• status:
  • 'doing': The current task is in progress.
  • 'done': The current task has completed successfully.

Note: On failure, the function will throw an error, and onProgressUpdate will not be called.

Example:

const onProgressUpdate = (info) => {
   console.log(info);
};

await ci.upload({
  project,
  version: '1.0.1',
  onProgressUpdate,
});

📄 License

MIT