Build a Custom Dashboard Widget with San CLI UI: From Zero to Publish

After previous sessions, this tutorial shows how to create a small widget displayed on the dashboard using San CLI UI.

Create Project

Use the UI plugin scaffold to generate a project named san-cli-ui-widget-hello. Key files are san.config.js, ui.js, and src/index.js. The directory structure is:

. 
├── README.md 
├── src 
│   └── index.js // component registration 
├── package.json 
└── ui.js // San CLI UI integration (plugin config)

In san.config.js, default configuration is generated via clientAddonConfig with a unique id and a local port:

const clientAddonConfig = require('san-cli-ui/client-addon-config');
module.exports = {
    ...clientAddonConfig({
        id: 'san.webpack.client-addon.san-cli-ui-widget-hello',
        port: 8890
    })
};

The ui.js file registers the addon path and defines the widget, handling both development and production environments:

module.exports = api => {
    if (process.env.SAN_CLI_UI_DEV) { // development
        api.registerAddon({
            id: 'san.widget.san-cli-ui-widget-hello.client-addon.dev',
            url: 'http://localhost:8890/index.js'
        });
    } else { // production
        api.registerAddon({
            id: 'san.widget.san-cli-ui-widget-hello.client-addon',
            path: 'san-cli-ui-widget-hello/dist'
        });
    }
    api.registerWidget({
        id: 'san.san-cli-ui-widget-hello.widget-demo',
        title: 'san-cli-ui-widget-hello.title',
        description: 'san-cli-ui-widget-hello.description',
        icon: 'smile',
        component: 'san.widget.components.widget-demo',
        minWidth: 2,
        minHeight: 2,
        maxWidth: 2,
        maxHeight: 2,
        maxCount: 1
    });
};

Local Debugging

1. Start Local Service

Run npm start inside the plugin project or use the San CLI UI interface to start the task.

2. Modify ui.js for Development

Comment out the production block so that only the development registration remains:

module.exports = api => {
    // if (process.env.SAN_CLI_UI_DEV) { ... }
    // else { ... }
    ...
};

3. Add Plugin as Dependency to a Local San Project

In the local project's package.json, add a devDependency pointing to the plugin folder:

{
  "devDependencies": {
    "san-cli-ui-widget-hello": "file:../san-cli-ui-widget-hello"
  }
}

4. Install Dependencies

Run npm i in the local project to install the new plugin.

5. View the Widget

Open the local project in San CLI UI; the newly added widget appears on the dashboard.

Publish

Restore the production code in ui.js, then execute npm run build && npm publish. After publishing, the widget can be found and installed via the San CLI UI plugin manager.

San is Baidu’s high‑performance MVVM framework, used in core Baidu APP services and open‑sourced with over 4.3K GitHub stars.