Integrating the Cheetah Core Module into uTools Plugin Development

The article begins by describing the uTools developer tool, which allows creating, running, and publishing plugins directly from the uTools marketplace.

Project Configuration : After installing the developer tool, a new project is created and a plugin.json file is added to define version, preload entry, logo, supported platforms, and feature commands such as open and setting .

{
  "version": "1.0.0",
  "preload": "index.js",
  "logo": "assets/logo.png",
  "platform": ["win32", "darwin"],
  "features": [
    {
      "code": "open",
      "explain": "搜索并打开项目",
      "cmds": ["open", "git_gui_open", "terminal_open", "folder_open", "set_application", "编辑器", "Git应用", "终端", "文件夹", "设置项目默认应用"]
    },
    {
      "code": "setting",
      "explain": "打开设置面板",
      "cmds": ["setting", "设置"]
    }
  ]
}

Settings Panel : Since uTools lacks built‑in preference UI, a custom settings window is created using HTML/CSS/JS and opened via utools.createBrowserWindow . The panel is built with Vite + Vue3 and bundled by Rollup.

File Structure shows the source layout, including lib , package (assets and plugin.json ), build configs, and the window folder containing the Vue UI.

cheetah-for-utools
├─ lib
│  ├─ common
│  │  ├─ constant.ts
│  │  ├─ core.ts
│  │  ├─ index.ts
│  │  └─ utils.ts
│  ├─ index.ts
│  └─ mount.ts
├─ package
│  ├─ assets
│  │  ├─ empty.png
│  │  ├─ logo.png
│  │  └─ …
│  └─ plugin.json
├─ rollup.config.js
├─ tsconfig.json
├─ vite.config.ts
└─ window
   ├─ index.html
   └─ src
      ├─ App.vue
      ├─ components
      └─ …

Integrating the Core Module : The Cheetah core is installed via npm install cheetah-core (or Yarn) and imported in the plugin code. Search functionality uses filterWithCache and filterWithSearchResult from the core, with a refresh keyword to bypass cache.

npm install cheetah-core
# or
yarn add cheetah-core

The search function builds the result list, adds a “refresh cache” item when needed, and handles empty results.

async function search(action, keyword, callbackSetList) {
  try {
    initCore();
    const needRefresh = keyword.includes(refreshKeyword);
    const searchKeyword = keyword.replace(refreshKeyword, '');
    if (!searchKeyword) return callbackSetList();
    let projects = await filterWithCache(searchKeyword);
    let fromCache = true;
    if (!projects.length || needRefresh) {
      projects = await filterWithSearchResult(searchKeyword);
      fromCache = false;
    }
    const result = output(projects);
    if (fromCache) {
      result.push({
        title: '忽略缓存重新搜索',
        description: '以上结果从缓存中获得,选择本条将重新搜索项目并更新缓存',
        icon: 'assets/refresh.png',
        arg: searchKeyword,
      });
    }
    if (!result.length) {
      result.push({
        title: `没有找到名称包含 ${searchKeyword} 的项目`,
        description: '请尝试更换关键词，回车返回重新搜索',
        icon: 'assets/empty.png',
        type: 'empty',
      });
    }
    callbackSetList(result);
  } catch (error) {
    errorHandle(error);
  }
}

Select Handling : The select callback processes the chosen item, opens the project with the appropriate application, or triggers a cache refresh.

function commonSelect(itemData) {
  const { arg, type } = itemData;
  if (type === 'empty') {
    utools.setSubInputValue('');
    return true;
  }
  const skip = arg !== null && arg !== undefined;
  if (skip) {
    utools.setSubInputValue(`${refreshKeyword}${arg}`);
  }
  return skip;
}

Platform‑specific commands are provided for macOS ( open -a "AppName" path ) and Windows (application path + project path, with special handling for PowerShell and CMD).

# macOS example
open -a "Visual Studio Code" /Users/.../test

# Windows example
"D:\Program Files\JetBrains\WebStorm 2021.1.1\webstorm.exe" "D:\works\test"

Cache Management : A button in the settings panel calls clearCache() from the core and shows a success notification.

export async function onClearCache() {
  try {
    initCore();
    await clearCache();
    notice('缓存清除成功');
  } catch (error) {
    errorHandle(error);
  }
}

Setting Project Applications : Users can assign a specific editor or tool to a project via utools.showOpenDialog , storing the path in the cache for later use.

export function chooseFile() {
  return utools.showOpenDialog({
    filters: [{ extensions: ['app', 'exe', 'lnk'] }],
    properties: ['openFile'],
  });
}

Error Handling : Core functions throw error codes; the plugin maps them to messages and displays them with utools.showNotification .

export function errorHandle(error) {
  const errorCode = error.message;
  notice(ErrorCodeMessage[errorCode]);
  utools.hideMainWindow();
}

Submission for Review : After building the plugin, developers open the uTools developer tool, select the project, fill version information, upload screenshots, and submit. The preload.js file must remain readable for the review process.

Conclusion : The Cheetah for uTools plugin is now complete (v1.2.0), open‑source, and ready for download. Future articles will cover adapting the core module for Alfred.