「这是我参与11月更文挑战的第2天,活动详情查看: 2021最后一次更文挑战 」
最近遇到一个情况,自己的开发机不在身边,需要开发一个 NPM 包,于是尝试使用了 Github codespaces 进行开发,这篇文章记录一下开发过程。
相关介绍:
Github codespaces
codespace 是 github 推出的云开发环境,提供了开发机和 web 编辑器,可以只使用浏览器开发工程。这类产品之前也有很多,这次是官方推出的。目前企业用户付费使用,而之前申请过内测的个人用户现在还可以免费使用。
Github actions
Github actions 是 github 推出的 ci/cd 工具,我们可以用来完成 NPM 包自动化发布。
我遇到的需求是我需要在网页上使用 SharedArrayBuffer(详细了解 SharedArrayBuffer ),此 API 要运行在 cross-origin-isolation 环境下,因此需要 server 添加 Cross-Origin-Opener-Policy 和 Cross-Origin-Embedder-Policy 的 header,我需要一个中间件来完成 header 添加。
创建仓库:
直接在 github 上创建即可,可以为自己的项目选择一个 LICENSE,这里我选择的 MIT。
创建好了之后进入工程主页,在仓库主页上,克隆代码的地方多了 tab,可以选择克隆到本地也可以使用 codespace,这里创建一个新的 codespace:
之后就可以打开一个编辑器页面,这是一个 web 版本的 vscode,可以同步 vscode 的配置和插件,大部分插件都可以在 web 版本中正常工作,开发体验很好:
初始化 NPM 工程:
codespace 中可以使用 terminal,因此这里和在本地一样,执行命令即可:
npm init
这里 package.json 中的 description 和 keywords 字段要写的详细一些,便于在 npm 上搜索。
添加 README:
readme 的目的是描述清楚仓库的作用,同时也会用作 npm 的使用文档,因此 readme 最基本的要求是要有包的使用方法。
为了提升通用性 readme 要用英文,有条件可以添加多语言 readme。
因为只是一个添加 header 的中间件,功能非常简单,因此这里直接使用 js 编写
'use strict';
* isolated middleware
* @return {Function} isolated middleware
* @api public
module.exports = function() {
return function isolated(ctx, next) {
ctx.set('Cross-Origin-Opener-Policy', 'same-origin');
ctx.set('Cross-Origin-Embedder-Policy', 'require-corp');
next();
作为一个通用的 NPM 包,测试用例必不可少,由于此包是一个 http 服务中间件,这里借助 supertest 工具来编写网络请求测试:
'use strict';
const assert = require('assert');
const Koa = require('koa');
const request = require('supertest');
const isolated = require('../');
describe('isolated.test.js', function () {
const app = new Koa();
app.use(isolated());
app.use(function (ctx) {
ctx.body = { foo: 'bar' };
it('should has the header `Cross-Origin-Opener-Policy` valued `same-origin` and `Cross-Origin-Embedder-Policy` valued `require-corp`', function (done) {
request(app.listen())
.get('/')
.expect('Cross-Origin-Opener-Policy', 'same-origin')
.expect('Cross-Origin-Embedder-Policy', 'require-corp')
.expect({ foo: 'bar' })
.expect(200, done);
创建 action:
在项目工程下创建 .github/workflows 目录,下面可以添加自己的 action。action 是一个 .yml 文件,这里我们创建一个 action 来自动发布 npm 包。
发布到 npm 需要提供 NPM_TOKEN,登录 www.npmjs.com/ 创建一个 Access Token 即可,类型选择 Automation,用于自动化发布。
token 信息是个人的信息凭证,不能硬编码到 action 文件中,这里可以使用 github 的 actions secrets 功能,在 settings 下 secrets 选项中,创建一个 secret 变量即可,在 action 代码中通过变量 ${{secrets.NPM_ACCESS_TOKEN}} 来读取。
这是我这个工程的 action 代码,每一步的name 字段描述了用途:
name: npm publish
push:
branches: [ main ]
jobs:
publish-npm:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [ 12.x ]
steps:
- name: checkout main
uses: actions/checkout@main
- name: setup Node.js
uses: actions/setup-node@master
with:
node-version: ${{ matrix.node-version }}
- name: version
id: version
uses: ashley-taylor/read-json-property-action@v1.0
with:
path: ./package.json
property: version
- name: publish to npm
run: |
npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
npm publish
NPM_TOKEN: ${{secrets.NPM_ACCESS_TOKEN}}
- name: create GitHub Release
id: create_release
uses: actions/create-release@latest
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: v${{steps.version.outputs.value}}
release_name: v${{steps.version.outputs.value}}
draft: false
prerelease: false
push 代码:
最后完成的代码直接 add && commit && push 即可,由于我们之前设置了 action 的触发器,代码 push 后会自动执行 actions 流程,在 actions 页面可以查看执行情况:
这里看到已经成功发布到 npm,到 npm 网站上可以搜索到刚刚发布的包:
至此,我只在浏览器中完成了 npm 包的发布工作,在没有开发环境的场景下还是很方便的,感兴趣可以体验一下。最后附两个 NPM 包地址(一个 koa 版本一个 express/connect 版本):
大家如果遇到使用 SharedArrayBuffer 或者其他需要 cross-origin-isolation 环境的 API 时可以安装使用(大部分场景都不需要)。