Introduction to San CLI: Purpose, Usage, and Plugin Development

This article is the first part of a series about San CLI, focusing on its purpose, basic usage, and key features.

What is a CLI? A command‑line interface (CLI) is a text‑based way to interact with a computer, offering advantages such as remote operation, automation, and lower resource consumption compared with graphical user interfaces.

What is San CLI? San CLI is the command‑line tool for the San front‑end framework. It bundles Webpack and provides commands that streamline project creation, development, debugging, and deployment, thereby improving developer productivity.

Why build a CLI? The CLI serves as a production tool that directly boosts productivity, integrates best‑practice solutions, and standardizes projects so that upgrading the CLI propagates improvements across all projects. It also aims to become a customizable front‑end engineering solution that abstracts away Webpack configuration.

Core functionalities:

Project creation: run san init xxx to scaffold a new San project. During initialization the CLI asks for project name, description, author, template engine, ESLint options, CSS pre‑processor, demo installation, and whether to install dependencies.

Development server: run san serve to start a local server with hot‑reload. The command prints a URL and QR code for previewing the app on devices.

Production build: run san build to generate optimized assets. For remote deployment use san build --remote <remote-name>.

Inspect Webpack config: run san inspect (optionally with --rules or --rule postcss) to view internal Webpack settings.

Graphical UI: run san ui to open a GUI that provides the same commands plus project management and news reading features.

Extending San CLI with plugins:

There are two plugin types:

Command plugins add new CLI commands. Example san-command-hello.js defines a hello command that accepts a --name option and prints a greeting. The plugin is registered in package.json under the san.commands field.

exports.command = 'hello';
exports.builder = { name: { type: 'string' } };
exports.desc = 'Greet the specified name';
exports.handler = argv => {
    console.log(`${argv.name}，你好呀！`);
};

Service plugins interact with the internal Webpack configuration. Example san-cli-plugin-get-entry.js logs the entry points during the build process via api.configWebpack. The plugin is added to the plugins array in san.config.js, optionally with custom parameters.

module.exports = {
    id: 'san-cli-plugin-get-entry',
    apply(api, projectOptions, options) {
        api.configWebpack(webpackConfig => {
            console.log('options: ', options);
            console.log('webpackConfig.entry: ', webpackConfig.entry);
        });
    }
};

Both plugin types can be published as npm packages (e.g., san-cli-command-hello or san-cli-plugin-get-entry) for reuse across projects.

The article concludes by encouraging readers to try San CLI, explore its many additional features (such as bundle analysis, markdown site generation, etc.), and stay tuned for the next part covering the implementation details.