{"id":19139952,"url":"https://github.com/arcblock/blocklet-spec","last_synced_at":"2026-03-03T04:10:36.430Z","repository":{"id":96024949,"uuid":"270967494","full_name":"ArcBlock/blocklet-spec","owner":"ArcBlock","description":"Blocklet specification [draft]","archived":false,"fork":false,"pushed_at":"2020-07-02T04:24:17.000Z","size":62,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-13T04:05:30.602Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArcBlock.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-09T10:05:11.000Z","updated_at":"2020-07-08T15:31:05.000Z","dependencies_parsed_at":"2023-04-24T16:47:35.383Z","dependency_job_id":null,"html_url":"https://github.com/ArcBlock/blocklet-spec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ArcBlock/blocklet-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcBlock%2Fblocklet-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcBlock%2Fblocklet-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcBlock%2Fblocklet-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcBlock%2Fblocklet-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArcBlock","download_url":"https://codeload.github.com/ArcBlock/blocklet-spec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArcBlock%2Fblocklet-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30031981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T03:27:35.548Z","status":"ssl_error","status_checked_at":"2026-03-03T03:27:09.213Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T07:15:45.291Z","updated_at":"2026-03-03T04:10:36.411Z","avatar_url":"https://github.com/ArcBlock.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## 什么是 Blocklet？\n\nBlocklet 是一种应用协议，同时也是一种软件架构。作为一个协议，它描述了构建 ABT Node 平台的方式；做为一个软件架构, 一个独立的 Blocklet 是一个可重用的软件模块，可能是一个 HTTP 服务，也可能是一个函数库等等；当多个 Blocklet 在一起运行时，需要一个平台将它们组合起来，共同构成一个独立的服务，比如 ABT 节点(ABT Node).\n\n## 如何定义 Blocklet？\n\n我们用 JSON 数据格式来描述 Blocklet 的协议。\n\n## 定义基本信息\n\n```json\n{\n  \"name\": \"blocklet name, can be same as npm package name\",\n  \"description\": \"blocklet description, can be same as npm package description\",\n  \"version\": \"blocklet version, can be same as npm package version\",\n  \"group\": \"only `dapp|static` are allowed and supported\"\n}\n```\n\nname, description, version, group 描述了 Blocklet 的基本信息。其中，group 分为 `dapp` 和 `static` 两种类型。`dapp` 就是常规的 dapp，static 是一中只包含了前端静态资源的 Web 应用，ABT Node 内部会用一个 HTTP Server 来 serve `static` Blocklet. \n\n## 定义运行时设置\n\n```json\n{\n  \"main\": \"the entrypoint to bundle the blocklet or the static folder\",\n  \"requiredEnvironments\": {\n    \"name\": \"string, name of the environment\",\n    \"description\": \"string, description of the environment\",\n    \"required\": \"bool, is required\",\n    \"default\": \"Any type, default value\"\n  }\n}\n```\n\n除了对 Blocklet 基本信息的描述，Blocklet 还定义了`main` 这个字段描述 Blocklet 如何开始运行，就是所谓的入口文件的描述。 这个字段和 Blocklet 的运行密切相关。`main` 定义了 dapp 或者 static 类型的 Blocklet 的入口文件或静态资源目录。所以对于 ABT Node 来说，`main` 字段是必须的，至关重要，否则 ABT Node 没有办法启动 Blocklet.\n\n除了 main 字段，我们还定义了 `requiredEnvironments` 字段用来声明 Blocklet 运行时需要的环境变量。有四个属性描述一个环境变量：name, description, required, default. 设置为 required 的变量，并且没有提供默认值时，用户必须在启动前设置该变量。\n\n`requiredEnvironments` 不是必须的，Blocklet 需要时可以通过这个字段要求 Blocklet 用户提供相应的信息。比如，Blocklet 依赖 MongoDB 数据库，那么就可以用 requiredEnvironments 来要求用户填写 MongoDB 的连接字符串。\n\n## 其他配置\n\n```json\n{\n  \"provider\": \"arcblock|community\",\n  \"public_url\": \"public page url, should at least specify one\",\n  \"admin_url\": \"administrator page url, default to empty\",\n  \"config_url\": \"configuration page url, default to empty\",\n  \"doc_url\": \"public document url, if not specified, will use registry detail page\"\n}\n```\n\n这里是其它的配置项，对于 Blocklet 来说这些字段是可以选的，我们简单的介绍一下这几个字段\n\n- provider 是声明 Blocklet 的来源，可选值有两个：arcblock|community. `arcblock` 代表 ArcBlock 官方开发的，`community` 是社区开发的。\n- public_url 是 Blocklet 可公开访问的地址。\n- admin_url 是 Blocklet 管理端地址。\n- config_url 是 Blocklet 配置页面地址。\n- doc_url 是 Blocklet 的文档地址，如果这个地址不存在，ABT Node 会使用 Blocklet 的 README 作为文档页面。\n\n## Blocklet 生命周期\n\n## 生命周期\n\n![blocklet lifecycle](./blocklet-lifecycle.png)\n\n在 ABT Node 中, Blocklet 完整的生命周期包括 安装（或部署）、启动、停止、卸载 这四个阶段。因为可以通过两种方式来安装 Blocklet, 分别是在 Marketplace 中下载安装，另外一种是直接在本地用 ABT Node CLI 部署安装。用 CLI 部署主要是为了开发测试。所以在生命周期的第一阶段中存在安装、部署两种情况。\n\n## Hooks\n\n![blocklet lifecycle](./blocklet-lifecycle-hooks.png)\n\n在在这几个阶段中，ABT Node 提供了 hook 功能，用来在执行生命周期的过程中做一些事情。目前包含：pre-deploy, post-install, pre-start, pre-stop, pre-install, pre-uninstall 这几个 Hook.\n\n比如，某个 Blocklet 对于运行的机器有硬件要求：内存不能低于 1G，可用磁盘容量不能低于 500 MB。这个时候就可以利用 pre-install hook 来检测目标机器是否已满足需求，如果满足，正常安装，否则抛出错误消息，并终止安装。\n\nhook 其实是一些 Shell 脚本，而这些脚本可能会引用 Blocklet 中的文件，而在打包 Blocklet 的过程中，ABT Node 打包工具(ABT Node CLI)会将 hook 用到的文件单独打包，所以，开发者需要在 `hookFiles` 中声明哪些文件被 hooks 引用了。\n\n## 如何开发 Blocklet？\n\n在了解了一些基础的 Blocklet 概念和协议后，那么怎么开发一个 Blocklet 呢？\n\n## 初始化 Blocklet\n\nABT Node CLI 提供了 `abtnode blocklet:init` 命令来帮助开发者快速创建一个 Blocklet 项目，这个命令会帮助开发者创建相关的配置文件和目录。\n\n### 代码结构\n\n```shell\n├── blocklet.json\n├── blocklet.md\n└── package.json\n```\n\n项目创建完成后，我们可以看到一个 Blocklet 项目主要包含两部分：Blocklet 描述信息和源代码。\nABT Node 当前只支持 Node.js 的 Blocklet 项目，所以 Blocklet 的描述信息一般会包含包含两部分：Node.js 的 package.json 和 Blocklet 的 blocklet.json. 我们在前面讲的 Blocklet Spec 的内容会放在 blocklet.json 中。当然，Blocklet 也允许将 blocklet.json 的内容放到 package.json 的 `blocklet` 字段中。 \n\n### blocklet.json\n\nBlocklet 所有的描述信息都放在 blocklet.json 文件中。\n前面我们说，Blocklet 是一个 Node.js 项目，我们知道，Node.js 的 package.json 文件中也包含 name, description, version 这些信息。对于 Blocklet 来说，这部分重复的信息是等价的，ABT Node 会优先读取 blocklet.json 的配置，如果没有，才会去读取 package.json 中的。\n\n如下是 blocklet.json 例子。\n\n```json\n{\n  \"name\": \"static-demo-blocklet\",\n  \"description\": \"Demo blocklet that shows how to serve a static html5 game with ABT Node\",\n  \"version\": \"1.0.0\",\n  \"group\": \"static\",\n  \"color\": \"primary\",\n  \"main\": \"app/\",\n  \"provider\": \"arcblock\",\n  \"requiredEnvironments\": {\n    \"name\": \"DEBUG\",\n    \"description\": \"Enable test flag\",\n    \"required\": false,\n    \"default\": \"arcblock*\"\n  }\n}\n```\n\n## Blocklet 环境变量\n\n之后的开发工作就是一个普通的 Web 应用开发了。因为 Blocklet 是运行在 ABT Node 节点中，所以 Blocklet 会依赖于 ABT Node 的环境。ABT Node 现在提供了一些环境变量供开发使用。\n\n### 私有环境变量\n\n- BLOCKLET_PORT\n- BLOCKLET_APP_DIR\n- BLOCKLET_DATA_DIR\n- BLOCKLET_LOG_DIR\n- BLOCKLET_CACHE_DIR\n- BLOCKLET_APP_SK\n- BLOCKLET_APP_ID\n- BLOCKLET_BASE_URL\n\n## 全局环境变量\n\n- ABT_NODE_DID\n- ABT_NODE_PK\n- ABT_NODE_URL\n- ABT_NODE_DOMAIN\n- ABT_NODE_PROTOCOL\n\n这些变量都是字面意思，在开发 Blocklet 过程中可以从环境变量中读取这变量的些值。\n\n## 如何打包 Blocklet？\n\nBlocklet 开发完成后需要将代码打包才能进行部署，ABT CLI 提供了 `abtnode bundle` 命令来打包源码。\n\n### 在 ABT Node 中测试\n\n在了解 Blocklet 声明周期一节时， 我们提到了部署(Deploy)阶段，这个命令可以将打包好的项目部署到本地 ABT Node 节点中，用来测试 Blocklet.\n\n## 如何发布 Blocklet？\n\n首先，将开发好的 Blocklet 发布到 NPM。`abtnode bundle` 命令会将打包好的代码放到当前目录的 `_blocklet` 目录中，在发布或者测试时，需要将 `_blocklet` 中代码打包发布。\n\n然后 fork https://github.com/arcblock/blocklets 仓库，（当然，如果没有 Github 账号的话，需要先注册一个 Github 账号）。\n修改项目的 registry.yml 文件，将自己的 Blocklet NPM 包地址放到 registry.yml 列表中。然后给 ArcBlock 的仓库： https://github.com/arcblock/blocklets 提一个 Pull Request。\n\nReview 确认没问题后，会将上面创建的 PR 合并到 Blocklet 仓库的主分支，从而完成发布。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcblock%2Fblocklet-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farcblock%2Fblocklet-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcblock%2Fblocklet-spec/lists"}