Submit your library to cdnjs (version 2022)

Have a producer mindset . Don't just be a consumer, use it as a doctrine, and then resent that the world is not perfect when you can't find it.

background

cdnjs is an excellent open source software CDN service, and the well-known bootCDN is its domestic mirror. Therefore, after submitting to cdnjs, it can be accessed through bootCDN.

I released wangEditor5 (an open source rich text editor) more than two months ago. I used jsDelivr as a CDN service at first, but it died some time ago. Using unpkg now , vaguely remember when it was unstable 1-2 years ago.

So, I want to synchronize wangEditor5 to cdnjs. But I didn't find the Chinese version when looking for the information, or it was outdated several years ago, so I found the English information from github, and translated it for others' reference.

Pre-Online 2020 methods no longer apply

cdnjs did a commit method update 2 years ago, so having a lot of outdated stuff is not applicable.

It probably means:

The cdnjs/cdnjs warehouse is currently limited to robot operations (some automatic operations) and no longer accepts pull requests. If you still want to continue submitting repositories to cdnjs, you can go to cdnjs/packages , or other open source repositories.

In fact, cdnjs/packages has the latest submission rules, which is the content to be translated in this article.

start translating

Original link github.com/cdnjs/packa…

Documentation directory

• Overview
• Policies, Rules and Guidance
• 配置 lib 自动更新
  • 自动更新概述
  • 自动更新配置
• 配置文件优化
• 在 cdnjs 创建新 lib
  • fork cdnjs 仓库
  • 修改你的 fork
  • 遵循已有 lib 的规则
  • 使用浏览器修改
  • 创建 pull request
  • 修复 CI 报错
  • 审查与合并

概述

cdnjs/packages 是一个 github 仓库，其中包含了很多 JSON 文件，它们控制着各个 lib 在 cdnjs.cloudflare.com 的可访问性。

cdnjs 依赖于用户提交 pull request 和自动更新的方式，来收集和更新 lib 。它包含很多贡献者和提交记录，所以通过正确的程序来提交 lib 是至关重要的。

以下两种形式的 lib 可被配置为自动更新（如何配置下文再说）

• 日常在 npm 上维护的
• github 仓库，且有 tag 和 release 的

那些无法自动更新的 lib 将不再被 cdnjs 支持。

政策、规则和引导

cdnjs 可以托管任何生产版本的 JS 和 CSS lib，只要有合适的 license 。

cdnjs 支持常见的文件格式，如 JS, TS, CSS, SCSS, JSON, WASM, SWF, images, audio ，所有的文件格式参考这个 API api.cdnjs.com/whitelist 。

【注意】cdnjs 对新提交的 lib 有如下要求，符合一个即可：

• npm 下载量 800+ 每月
• github 仓库有 200+ star

配置 lib 自动更新

自动更新概述

日常在 npm 维护的包，以及在 github 有 tag release 的仓库，可以被配置为自动更新。一个 cdnjs 的脚本会定期运行（每小时一次），检查相应的 npm 包或 github release 是否有新的版本发布，并更新到 cdnjs 中。

每一个 cdnjs 都有一个 JSON 文件，其中包含了该 lib 的一些信息。自动更新就配置在这个 JSON 文件里，和其他配置信息在一起。

自动更新配置

• autoupdate 一级属性，包含了所有自动更新的配置
  • source 如果是 npm 包则为 npm ，如果是 git 仓库则为 git
  • target npm 的名称，后者 git 仓库的 url
  • fileMap 数组或者对象，告诉 cdnjs 应该拷贝哪些文件
    • basePath 要拷贝文件的根目录
    • files 要拷贝的文件名，可以直接写名字（如 lodash.min.js）也可以用 *.js 形式

PS：如果在 files 中使用通配符，请一定严格填写，不要把一些无用的文件也包含进来，避免造成浪费。

npm 包 自动更新 配置示例

  "autoupdate": {
    "source": "npm",
    "target": "function-plot",
    "fileMap": [
      {
        "basePath": "dist",
        "files": [
          "*.js",
          "utils/*.js"
        ]
      }
    ]
  }

示例中 function-plot 包的目录结构如下

|__dist
| |__function-plot.js
| |__utils
| | |__plotter.js
|__bower.json
|__index.js
|__site.js
|__package.json
|__README.md
|__lib
| |__...
|__node_modules
| |__...
|__sandbox
| |__...

根据配置规则，自定更新程序将定位到 dist 目录（你在 basePath 配置了），然后拷贝其中的 *.js 和 utils/*.js（你在 files 中配置了）到 cdnjs 中。再去掉 dist 目录，最终的 cdnjs 的文件目录如下

|__ajax
  |__libs
    |__function-plot
      |__x.y.z
        |__function-plot.js
        |__utils
          |__plotter.js

其中 x.y.z 是版本号，和包的 package.json 文件中版本一致。

git 仓库 自动更新 配置示例

  "autoupdate": {
    "source": "git",
    "target": "git://github.com/mikehostetler/amplify.git",
    "fileMap": [
      {
        "basePath": "lib",
        "files": [
          "*.js"
        ]
      }
    ]
  }

配置中的这个 git 仓库有代码结构如下

|__demo
| |__...
|__docs
| |__...
|__external
| |__...
|__lib
| |__amplify-vsdoc.js
| |__amplify.core.js
| |__amplify.core.min.js
| |__amplify.js
| |__amplify.min.js
| |__amplify.request.js
| |__amplify.request.min.js
| |__amplify.store.js
| |__amplify.store.min.js
|__src
| |__...
|__test
| |__...
|__.gitignore
|__.jshintrc
|__GPL-LICENSE.txt
|__MIT-LICENSE.txt
|__bower.json
|__build.json
|__header.js
|__package.json
|__readme.md
|__test-jquery-versions.js
|__test-server.js
|__testswarm.json

根据配置规则，自定更新程序将定位到 lib 目录（你在 basePath 配置了），然后拷贝其中的 *.js （你在 files 中配置了）到 cdnjs 中。再去掉 lib 目录，最终的 cdnjs 的文件目录如下

|__ajax
  |__libs
    |__amplify
      |__x.y.z
        |__amplify-vsdoc.js
        |__amplify.core.js
        |__amplify.core.min.js
        |__amplify.js
        |__amplify.min.js
        |__amplify.request.js
        |__amplify.request.min.js
        |__amplify.store.js
        |__amplify.store.min.js

其中 x.y.z 是版本号。

配置文件优化

默认情况下，当有新文件被自动更新进来时，cdnjs 会对特定文件进行压缩。对于 JS CSS 文件，cdnjs 会压缩代码生成 filename.min.js 和 filename.min.css 文件。对于图片文件，cdnjs 也会进行压缩处理，以节省 CDN 的带宽。

如果你想禁用这个功能，你可以通过在 JSON 文件中配置 optimization 来控制。这个配置是可选的。示例如下：

"optimization": {
    "js": false,
    "css": false,
    "png": false,
    "jpg": false
  }

在 cdnjs 创建新 lib

流程概述

• Fork cdnjs/packages 仓库到你自己的 github 账户
• 对这个仓库进行必要的修改
• 提交一个 pull request 并附加合适的信息
• 带 PR 合并之后，删除掉你 fork 的仓库

Fork cdnjs/packages 仓库

通过 github.com/cdnjs/packa… 来 fork 仓库到你自己的 github 账号，然后你就有如下仓库了 github.com/your-github… 。

PS：请注意你 fork 的是 cdnjs/packages 而不是 cdnjs/cdnjs ，后者现在不再受理 pull reqeust

修改信息

在你 fork 的仓库中修改信息，这些信息将被提交 pull request ，最后会被 cdnjs 维护人员审查、合并。

修改信息可以通过浏览器，也可以使用 git 下载到本地…… （译者：最基本的 git 操作，这里就不说了）

译者注：
这里所说的“修改信息”，应该就是在 packages 这个仓库中，选择一个合适的文件夹（根据 lib 首字母），增加自己包的 JSON 文件，文件格式参考现有的即可，例如这个 jQuery.x18n.json 。

遵守已有 lib 的规则

When submitting a new lib, please refer to the naming and format of the existing lib, preferably the JSON format of the newly added lib.

Modify using a browser

Github is more convenient to add and modify files on web pages, which is very suitable for this scenario.

Go to this directory github.com/your-github… of your fork repository , go to the appropriate folder (according to the lib initials), and create a new JSON file. The file format refers to the existing ones.

Create pull request

After adding files, you can submit commits and create pull requests.

The commit information should follow the following standard format, which is convenient for cdnjs personnel to review:
Add <lib 的名字> w/ npm/git auto-update(choose one by npm/gityourself )

The commit description is not required.

Note that instead of committing to the masterbranch , choose to create a new branch with an appropriate branch name, e.g.add-my-lib-name

Finally, just create a pull request, and the cdnjs staff will review it as soon as possible.

Fix CI error

In order to ensure the correctness of the submitted JSON file format and the correct automatic update configuration, CI (github actions) will be automatically triggered during PR.

If CI checks the JSON file or is misconfigured, it is marked as failed. At this point you need to re-edit the JSON file and resubmit.

Review and Merge

If the CI check is successful, the cdnjs people will continue to manually review the PR content to ensure that there are no issues.

If there are no problems with manual review, the PR will be merged, and you can delete the previously forked repository.

Thanks for your contribution to cdnjs.

Translation ends

Finally, welcome to use the wangEditor5 open source rich text editor.