Mastering San CLI: From Project Creation to Custom Plugins

CLI (Command‑Line Interface) predates graphical user interfaces and remains essential for remote operations, automation, and low‑resource usage. San CLI is a built‑in Webpack command‑line tool that streamlines San project workflows, saving time and effort.

Why Build a CLI

Improving the CLI experience directly raises developer productivity. San CLI covers the entire lifecycle—project creation, development, debugging, building, and deployment—providing tailored solutions for each stage and enabling a unified, upgrade‑friendly engineering setup.

Core Features

Project creation : san init <project-name> scaffolds a new San project with interactive prompts.

Development server : san serve launches a local server, displays a URL and QR code, and supports hot‑reloading.

Production build : san build bundles the app for production, showing output size and paths.

Remote deployment : san build --remote <remote-name> deploys the build directly to a configured remote machine.

Inspection : san inspect reveals the full Webpack configuration; optional flags like --rules or --rule postcss limit the output.

Graphical UI : san ui opens a GUI that mirrors CLI capabilities and adds project management and news reading features.

Project Creation Details

Running san init xxx creates a folder xxx and initializes a San project. The CLI asks a series of questions whose answers populate package.json fields and project files:

Project name : used for package.json name and README.

Project description : fills the description field.

Author : sets the author field and file headers.

Template engine : choose “Smarty” or plain HTML; plain HTML is safe for beginners.

ESLint installation : optional code‑style checking.

ESLint config : select @ecomfe/eslint-config, Standard, or Airbnb.

lint‑staged : run ESLint on staged files before git commit; can be skipped with --no-verify.

Demo installation : adds example code for learning.

Demo type : choose between san-store and normal when a demo is installed.

CSS pre‑processor : pick less, Sass, or stylus.

Dependency installation : optional at init time.

The resulting project structure resembles the screenshot below.

Development Server

After creation, run san serve in the project directory. The CLI prints a URL and QR code; opening either shows the live development page with hot‑reload support.

Production Build and Remote Deployment

Execute san build to generate production assets. The CLI reports output paths and file sizes.

For remote deployment, use san build --remote <remote-name>. Proper environment and parameter configuration is required (see the official documentation).

Additional Utilities

Inspect Webpack Configuration

Run san inspect to view the full internal Webpack config. Use flags like --rules or --rule postcss to limit the output.

Graphical UI

Although named CLI, San also provides a GUI. Run san ui to open the interface, which adds project management and news reading features beyond the command line.

Extending San CLI with Plugins

San CLI supports two plugin types:

Command plugins : add custom commands (e.g., san hello --name <name>).

Service plugins : modify internal Webpack config or san.config.js behavior.

Command Plugin Example

Create san-command-hello.js with the following content:

exports.command = 'hello';
exports.builder = {
    name: { type: 'string' }
};
exports.desc = '热情地向给定对象打招呼';
exports.handler = argv => {
    console.log(`${argv.name}，你好呀！`);
};

Add the plugin path to package.json:

{
    "san": {
        "commands": ["./san-command-hello.js"]
    }
}

Running san hello --name 百度 prints “百度，你好呀！”. The command can be published as an npm package following the san-cli-command-* naming convention.

Service Plugin Example

Create san-cli-plugin-get-entry.js:

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

Configure it in san.config.js:

module.exports = {
    plugins: [
        "./san-cli-plugin-get-entry.js", "我是项目引入插件时传入的参数"
    ]
};

The plugins array contains the plugin path and optional parameters. Service plugins are instantiated when commands like san init or san build run, allowing them to hook into the build process.

After adding the service plugin, executing san build shows two extra log lines from the plugin, confirming its effect.

Service plugins can also be published as npm packages using the san-cli-plugin-* prefix and referenced via require('san-cli-plugin-*') in san.config.js.

Conclusion

The article covered San CLI’s purpose, core commands, UI, and how to extend it with custom command and service plugins. Additional capabilities such as bundle analysis, performance profiling, custom scaffolding, and Markdown site generation are also available. Stay tuned for the next part, which will dive into the implementation details.