小程序 boilerplate cli 工具教程

- 2017年的老文,搬运存档用 -

先打个广告,企鹅 FM 和微云的小程序已上线~ 请多多关照 (づ ̄ 3 ̄)づ

痛点发现

开发至今有两个痛点忍不下,需要写小工具来解决。

  1. 作为一个非常喜欢新建项目做测试的开发者来说,新建项目以后,从老项目中复制粘贴各种文件心很累… 迫切需要一个小程序 boilerplate,也就是项目模板。
  1. 每次新增一个页面时,命令好长…:touch pageName.wxml pageName.wxss pageName.js不想再打三次页面名字了。而且常常忘了要到 app.json 中注册页面

于是决定写个(100 行代码不到的) cli 工具解决痛点,另外选择了 npm package 的方式,方便维护。

开始

安装/更新环境

开发需要在 node 环境下,先安装/更新好环境,po 主本机环境如下:

创建 npm 项目

pacakage.json 直接使用默认配置,也就是一路回车,生成内容如下图的配置文件:

mkdir mywxapp-tmpl && cd mywxapp-tmpl && touch index1.js
npm init

思路

我希望这个命令行工具使用起来是这样的:

之前没有写过 cli 工具,所以在写下思路后有了三个疑问:

  1. 如何封装一个 cli 工具插件?编写一般的 npm 插件,是通过 module.exports 将插件接口暴露出来,继而使用者通过这个接口再去调用不同方法,但是一个命令行工具要如何执行我们的命令呢
  2. 如何根据不同的 options(上图中的 -i-p 即 options)执行不同的任务?要自己做 parser 吗?
  3. 项目模板要存储在哪里?有两条思路:单独维护模板;或者是将模板和插件打包在一起,每次更新模板的同时更新插件。用哪一个?

逐个解决:

  1. package.json 中有一个字段是 bin: { ... "bin": { "mywxapp": "./index.js" } } 这个字段可以将开发者希望执行的脚本注册到环境变量 (PATH) 中,不同的 key 对应执行不同的脚本。也就是说现在,当我们直接在命令行中执行 mywxapp 等价于在 terminal 中执行 ~/path/to/index.js 第一个问题解决,关于 bin 字段更多信息请参考 npm 文档中 package.json 一节
  2. 执行 index.js 时,可以通过 process.argv 获取执行时的输入值,但是要自己处理 options 无疑很麻烦。不过,node/npm 发展至今处理命令行参数这样满足刚需的库肯定存在,就是 commander。简单好用易上手,那么第二个问题也解决啦。
  1. 上文也提到了,我对模板位置的存储有两个方向的规划,最后选择的是将模板直接托管在可访问到的 git 仓库中。想到小程序框架迭代迅速,模板可能会需要跟着框架一起进化。 也可以看出 boilerplate 生成器本身的功能很简单,如果把模板封装进去,会增加代码量,而且工具更新应该是在修复 bug、新增功能这样的情况下,模板的更新不属于此范围。分开管理更合理。而且目前的模板还比较简陋,自动化的部分还没有整合上去,这些之后也会逐步跟上(至少 less -> wxss 得有…),可想改动会比较频繁。 download-git-repo 可以把给定地址的仓库内容拷贝到执行目录中。API 简单,所以就是它了。

实现

根据上面一节,先安装依赖的包:

npm install commander download-git-repo mkdirp --save

// 这个三个插件是使用时依赖,而不仅仅是开发依赖,所以用 --save // 在新建页面的时候,使用 mkdirp 新建对应的页面目录

加上 bin 字段,最后 package.json 中新增了内容:

{
    ...
    "dependencies": {
        "commander": "^2.9.0",
        "download-git-repo": "https://registry.npmjs.org/download-git-repo/-/download-git-repo-0.2.1.tgz",
        "mkdirp": "^0.5.1"
    },
    "bin": {
      "wxapp": "./index.js"
    }
}

generator 本身逻辑非常简单,参考上面一节的思路图,这里列一个不考虑出错情况的伪代码,不怕我的 JS 代码辣眼睛的也可以看这里

const program = require('commander');
const mkdirp = require('mkdirp');
const download = require('download-git-repo');

// 创建项目
function initProj(projName) {
  var projPath = currentDir + '/' + name;
  if(currentDir.exists(projName))
    console.warn(projName + '项目已经存在,请使用别的名字');
  else
    download('path/to/tmpl', currentDir+'/'+projName);
}

// 注册页面
function registerPage(pagesName) {
  var configFile = projPath + '/app.json';

  // 读配置文件
  readFile(configFile, function(data){
    // 将新建的所有页面都写入配置文件中
    for(name in pagesName){
      data.pages.push('pages/' + name + '/' + name);
    }
    writeFile(configFile);
  });
}
// 创建页面
function createPage(pages) {
  var pagePath = projPath + '/pages/';

  for(var index in pages) {
    var page = pages[index];
    mkdirp(pagePath, function(){
      open(pagePath+'/'+page+'.wxml', pagePath+'/'+page+'.wxss', pagePath+'/'+page+'.js');
    })
  }

  // 将页面注册到 app.json 中
  registerPage(pages);
}


// options 
program
  .usage('[options] <file ...>')
  .option('-i, --init [value]', '创建初始项目')
  .option('-p, --newpage <items>', '输入要创建的页面名称,不带任何扩展名,自动生成目录和对应的 .wxml .wxss 和 .js 文件', list)
  .parse(process.argv);


if(program.init != undefined) initProj(program.init);
if(program.newpage != undefined) createNewPage(program.newpage);

使用

要在本机全局使用的话,执行:

npm install -g

为保证全局环境统一,改了开发版本的代码以后,更新可以同步到全局,建议再执行:

npm link

(gif 过大无法展示,附件不允许添加图片…大家想象一下好了)

发布

使用 npm publish 发布到 npmjs 上,具体可以参考文档。 可以看到 npm 上已经有很多类似的插件了:

作为一个 boilerplate 可能会根据团队/个人需求不同而不同,发布一个自己常用的,方便在各个设备上拉取使用,所以 scoped package,你值得拥用,只是在发布和安装的时候需要敲比较长的包名,使用时不用:

有 scope 的包默认发布的时候是有私有的,这个是 npm 付费用户才能使用的权限,免费用户要发布这样的包需要带参数:

npm publish --access public

总结

终于不用一新建项目就看着祖国江山一片红的 console 了 ╰( ᐖ╰)≡(╯ᐛ )╯ ,关于为什么我的项目模板是这样规划的,请戳这里

在写平常的 web 需求时也会用到 boilerplate,不过只需要用 snippet 加快捷键就能解放了,小程序毕竟是一个初始化工程所以才做了一个 cli 工具。如果有更轻量的方法请告诉我~

参考资料

  1. 其他开发者写的工具:MeCKodo/wxapp-cli
  2. ES2015 & babel 实战:开发 NPM 模块
  3. Creating Your First Node.js Command-line Application
  4. Writing Command-Line Applications in NodeJS
  5. Building command line tools with Node.js
  6. npm-developers Developer Guide
  7. 如何使用NPM来管理你的Node.js依赖

其他小程序相关资源

吃瓜群众看到了资源并没有用过,随便放上来一下:

  1. 这个是在用的 · 还不错用的 ST snippet
  2. 更新及时的小程序开发汇总
  3. 小程序框架 wepy
  4. 另一个小程序框架 labrador

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区