From 7ab9ddf7665ff6ff89b0c237df87023f4b7dc43c Mon Sep 17 00:00:00 2001 From: jaywcjlove <398188662@qq.com> Date: Wed, 28 Sep 2022 13:35:52 +0800 Subject: [PATCH] feat: add `package.json` cheatsheet. --- README.md | 1 + docs/cron.md | 2 +- docs/git.md | 10 +- docs/javascript.md | 36 +-- docs/jest.md | 16 +- docs/json.md | 8 +- docs/markdown.md | 6 +- docs/npm.md | 2 +- docs/package.json.md | 597 +++++++++++++++++++++++++++++++++++++++ docs/sketch.md | 4 +- docs/toml.md | 6 +- docs/typescript.md | 28 +- docs/vscode.md | 2 +- scripts/create.mjs | 22 +- scripts/nodes/footer.mjs | 2 +- scripts/style.css | 83 +++--- 16 files changed, 715 insertions(+), 110 deletions(-) create mode 100644 docs/package.json.md diff --git a/README.md b/README.md index d84dbd5..51265f5 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Quick Reference ## 工具包 [npm](./docs/npm.md) +[package.json](./docs/package.json.md) [VSCode](./docs/vscode.md) [Sketch](./docs/sketch.md) [Jest](./docs/jest.md) diff --git a/docs/cron.md b/docs/cron.md index 5dfb1fc..f179b29 100644 --- a/docs/cron.md +++ b/docs/cron.md @@ -84,7 +84,7 @@ Min Hour Day Mon Weekday ### 特殊字符 - + | 特殊字符 | 说明 | diff --git a/docs/git.md b/docs/git.md index e8d1bdb..896c046 100644 --- a/docs/git.md +++ b/docs/git.md @@ -27,7 +27,7 @@ $ git clone git_url 指定目录 ``` ### 做出改变 - + 在工作目录中**显示**修改后的文件，为您的下一次提交暂存 @@ -368,10 +368,10 @@ $ git log -p ```shell $ git log --pretty=oneline --graph --decorate --all ``` - + ### 分支 - + 列出所有分支及其上游 @@ -442,7 +442,7 @@ $ git rm -r --cached <目录/文件> ``` ### 修改远程 Commit 记录 - + ```shell @@ -519,7 +519,7 @@ $ git rev-parse --short HEAD # e10721c ```shell $ git branch --merged master | grep -v '^\*\| master' | xargs -n 1 git branch -d ``` - + ### 中文乱码的解决方案 diff --git a/docs/javascript.md b/docs/javascript.md index 4a8ef38..d2a1341 100644 --- a/docs/javascript.md +++ b/docs/javascript.md @@ -127,7 +127,7 @@ let age = 7; ``` ### 字符串 - + ```js @@ -154,7 +154,7 @@ abc.split(""); ``` ### 数字 - + ```js @@ -211,7 +211,7 @@ Math.floor(Math.random() * 5) + 1; ``` ### 全局函数 - + ```js @@ -247,7 +247,7 @@ JavaScript 条件 ### 操作符 - + ```javascript @@ -401,7 +401,7 @@ const rocketToMars = function() { ``` ### 箭头函数 (ES6) - + #### 有两个参数 @@ -494,7 +494,7 @@ JavaScript 范围 ---- ### 范围 - + ```javascript @@ -793,7 +793,7 @@ for (let index in fruits) { ``` ### label 语句 - + ```js @@ -827,7 +827,7 @@ for (let fruit of fruits) { ``` ### for await...of - + ```javascript @@ -972,7 +972,7 @@ console.log(classElection.place); // undefined ``` ### 可变的 - + ```javascript @@ -1041,7 +1041,7 @@ console.log(origObj.color); ``` ### 工厂函数 - + ```javascript @@ -1119,7 +1119,7 @@ JavaScript Classes ---- ### 静态方法/字段 - + ```javascript @@ -1311,7 +1311,7 @@ JavaScript Promises ---- ### Promise - + 创建 promises @@ -1416,7 +1416,7 @@ promise.catch((err) => { ``` ### Promise.all() - + ```javascript @@ -1457,7 +1457,7 @@ promise.then(res => { ``` ### 避免嵌套的 Promise 和 .then() - + ```javascript @@ -1484,7 +1484,7 @@ JavaScript Async-Await ### 异步 - + ```javascript @@ -1611,7 +1611,7 @@ req.send(); ``` ### POST - + ```javascript @@ -1634,7 +1634,7 @@ xhr.onerror = () => { ``` ### fetch api - + ```javascript @@ -1695,7 +1695,7 @@ fetch('https://api-xxx.com/endpoint', { ``` ### async await 语法 - + ```javascript diff --git a/docs/jest.md b/docs/jest.md index da3e7a8..2b95e98 100644 --- a/docs/jest.md +++ b/docs/jest.md @@ -17,7 +17,7 @@ Jest 是一款优雅、简洁的 JavaScript 测试框架。 - 代码覆盖， 无需其他操作，您仅需添加 --coverage 参数来生成代码覆盖率报告。 ### 测试结构 - + ```js @@ -150,7 +150,7 @@ expect([{ a: 1 }, { b: 2 }]).toEqual([ ``` ### 模拟函数 - + ```js @@ -293,7 +293,7 @@ expect(fn).toThrowErrorMatchingSnapshot() ---- ### 实例 - + 请参阅 Jest 文档中的 [更多示例](https://jestjs.io/docs/en/tutorial-async)。 @@ -330,7 +330,7 @@ test('async test', async () => { ``` ### done() 回调 - + ```js @@ -371,7 +371,7 @@ test('async test', () => { ## 模拟 ### 模拟函数 - + ```js @@ -409,7 +409,7 @@ const callback = jest.fn(() => true) [模拟函数文档](https://jestjs.io/docs/en/mock-function-api) ### 返回、解析和拒绝值 - + 您的模拟可以返回值： @@ -504,7 +504,7 @@ const setTitle = jest ``` ### 定时器模拟 - + 为使用本机计时器函数（`setTimeout`、`setInterval`、`clearTimeout`、`clearInterval`）的代码编写同步测试。 @@ -556,7 +556,7 @@ Object.defineProperty(location, 'title', { ``` ### 清除和恢复模拟 - + 对于一个模拟 diff --git a/docs/json.md b/docs/json.md index fd713ab..d5d80fb 100644 --- a/docs/json.md +++ b/docs/json.md @@ -47,7 +47,7 @@ JSON 备忘清单 ### 字符串 - + | | | @@ -82,7 +82,7 @@ Have to be delimited by double quotes ### 数字 - + | Type | Description | @@ -229,7 +229,7 @@ let myObject = { ### 访问嵌套 - + ```javascript @@ -273,7 +273,7 @@ let myObject = { ### 访问对象数组 - + ```javascript diff --git a/docs/markdown.md b/docs/markdown.md index 053bb23..2bf40d2 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -42,7 +42,7 @@ Header 2 ``` ### 无序列表 - + ```markdown @@ -166,7 +166,7 @@ console.log("This is a block code") ``` ### 表格 - + ```markdown @@ -188,7 +188,7 @@ console.log("This is a block code") Markdown 表格生成器：[tableconvert.com](https://tableconvert.com/) ### 图片 - + ```markdown diff --git a/docs/npm.md b/docs/npm.md index d7a0e15..06be78f 100644 --- a/docs/npm.md +++ b/docs/npm.md @@ -56,7 +56,7 @@ npm 备忘清单 ### 杂项功能 - + 将某人添加为所有者 diff --git a/docs/package.json.md b/docs/package.json.md new file mode 100644 index 0000000..3be09de --- /dev/null +++ b/docs/package.json.md @@ -0,0 +1,597 @@ +package.json 备忘清单 +=== + +这个快速参考备忘清单，显示了关于 package.json 文件中所需内容的全部内容。 + +重要字段 +---- + +### 介绍 + +本快速参考备忘清单是您需要了解的关于 package.json 文件中所需内容的全部内容。 它必须是实际的 JSON，而不仅仅是 JavaScript 对象字面量。 + +- [npm 文档](https://docs.npmjs.com/files/package.json) _(npmjs.com)_ +- [yarnpkg 文档](https://classic.yarnpkg.com/en/docs/package-json) _(yarnpkg.com)_ + +### `name` + +```json +{ + "name": "my-awesome-package" +} +``` + +**规则** + +- 必须小于或等于214个字符(包括 `@scope/` 范围包) +- 不能以点（`.`）或下划线（`_`）开头 +- 名称中不得包含大写字母 +- 必须仅使用URL安全字符 + +### `version` + +```json +{ + "version": "1.0.0" +} +``` + +包的当前版本，严格遵循 [Semantic Versioning 2.0.0](http://semver.org/lang/zh-CN/) 语义化版本规范。 + +### Tips + +- 不要使用和 `Node.js` 核心模块相同的名字。 +- 不要在名字里包含 `js` 或者 `node` 单词。 +- 短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 `require()` 调用里。 +- 保证名字在 [npm registry](https://www.npmjs.com/) 里是唯一的。 +- name 和 version 字段一起用于创建唯一ID + +如果没有 `name` 和`version` 字段，您的包将无法安装 + +### 安装 `name` 包 + + + +```sh +yarn add [包名] +# or +npm install [包名] +``` + +安装后存放位置 + +``` +node_modules/[包名] +``` + +npmjs 下载地址 + +``` +https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz +``` + + +这是您的 `包` 的名称。 它在URL中使用，作为参数命令行，以及 `node_modules` 中的目录名。 + +信息类字段 +---- + +### `description` + +```json +{ + "description": "我的包的概要简短描述" +} +``` + +帮助使用者了解包的功能的字符串，包管理器也会把这个字符串作为搜索关键词。 + +### `license` + + + +所有包都应该指定许可证，以便让用户了解他们是在什么授权下使用此包，以及此包还有哪些附加限制。 + +```json +{ + "license": "MIT", + "license": "(MIT or GPL-3.0)", + "license": "SEE LICENSE IN LICENSE_FILENAME.txt", + "license": "UNLICENSED" +} +``` + +鼓励使用开源 [(OSI-approved)](https://opensource.org/licenses/alphabetical) 许可证，除非你有特别的原因不用它。 如果你开发的包是你工作的一部分，最好和公司讨论后再做决定。 + +**license字段必须是以下之一:** + +- 如果你使用标准的许可证，需要一个有效地 [SPDX 许可证标识](https://spdx.org/licenses/)。 +- 如果你用多种标准许可证，需要有效的 [SPDX 许可证表达式2.0语法表达式](https://www.npmjs.com/package/spdx)。 +- 如果你使用非标准的许可证，一个 `SEE LICENSE IN <文件名>` 字符串指向你的包里顶级目录的一个 <文件名>。 +- 如果你不想在任何条款下授权其他人使用你的私有或未公开的包，一个 `UNLICENSED` 字符串。 + +### `keywords` + +```json +{ + "keywords": [ + "short", "relevant", "keywords" + ] +} +``` + +一个字符串数组，当在包管理器里搜索包时很有用。 + +链接类字段 +---- + +各种指向项目文档、issues 上报，以及代码托管网站的链接字段。 + +### `homepage` + +```json +{ + "homepage": "https://your-package.org" +} +``` + +是包的项目主页或者文档首页。 + +### `repository` + + + +```json +{ + "repository": { + "type": "git", "url": "https://github.com/user/repo.git" + }, + "repository": "github:user/repo", + "repository": "gitlab:user/repo", + "repository": "bitbucket:user/repo", + "repository": "gist:a1b2c3d4e5f" +} +``` + +包的实际代码所在的位置。 + +### `bugs` + +```json +{ + "bugs": "https://github.com/user/repo/issues" +} +``` + +问题反馈系统的 URL，或者是 email 地址之类的链接。用户通过该途径向你反馈问题。 + +项目维护类字段 +---- + +### `author` + +项目的维护者。 + +```json +{ + "author": { + "name": "Your Name", + "email": "you@xxx.com", + "url": "http://your-x.com" + }, + "author": "Your Name (http://your-x.com)" +} +``` + +作者信息，一个人。 + +### `contributors` + + + +```json +{ + "contributors": [ + { "name": "Your Friend", "email": "friend@xxx.com", "url": "http://friends-xx.com" } + { "name": "Other Friend", "email": "other@xxx.com", "url": "http://other-xx.com" } + ], + "contributors": [ + "Your Friend (http://friends-xx.com)", + "Other Friend (http://other-xx.com)" + ] +} +``` + +贡献者信息，可能很多人。 + +## 文件类信息 + +指定包含在项目中的文件，以及项目的入口文件。 + +### `files` + +```json +{ + "files": [ + "filename.js", + "directory/", + "glob/*.{js,json}" + ] +} +``` + +项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。 + +### `main` + +```json +{ + "main": "filename.js" +} +``` + +项目的入口文件。 + +### `man` + +```json +{ + "man": "./man/doc.1", + "man": ["./man/doc.1", "./man/doc.2"] +} +``` + +项目的入口文件。 + +### `directories` + +```json +{ + "directories": { + "lib": "path/to/lib/", + "bin": "path/to/bin/", + "man": "path/to/man/", + "doc": "path/to/doc/", + "example": "path/to/example/" + } +} +``` + +当你的包安装时，你可以指定确切的位置来放二进制文件、man pages、文档、例子等。 + +### `bin` + +```json +{ + "bin": "bin.js", + "bin": { + "命令名称": "bin/命令路径/命令名称.js", + "other-command": "bin/other-command" + } +} +``` + +随着项目一起被安装的可执行文件。 + +### `types` + +这是一个只在 [TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 中生效的字段，如果您的包有一个 `main.js` 文件，您还需要在 `package.json` 文件中指明主声明文件。 将 `types` 属性设置为指向 `bundled` 的声明文件。 例如： + +```json +{ + "types": "./lib/main.d.ts", +} +``` + +如果您的主声明文件名为 `index.d.ts` 并且位于包的根目录（`index.js`旁边），则不需要标记 `types` 属性，建议这样做。 + +## 打包包字段 + +### `esnext` + + + +完整的[提案在这里](http://2ality.com/2017/04/transpiling-dependencies-babel.html)。 简短说明： + +- `esnext`：ES模块中使用阶段4功能（或更旧版本）的源代码，未编译。 +- `main`：指向一个CommonJS模块（或UMD模块），其 `JavaScript` 与 `Node.js` 当前可以处理的一样现代。 +- 大多数 `module` 用例应该可以通过 `esnext` 处理。 +- `browser` 可以通过 `esnext` 的扩展版本来处理 + +```json +{ + "main": "main.js", + "esnext": { + "main": "main-esnext.js", + "browser": "browser-specific-main-esnext.js" + } +} +``` + +另请参阅：[通过 npm 交付未编译的源代码](http://2ality.com/2017/06/pkg-esnext.html) + +### `module` + +`pkg.module` 将指向具有 `ES2015` 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述[在这里](https://github.com/rollup/rollup/wiki/pkg.module)。 + +```json +{ + "module": "dist/my-package.esm.js" +} +``` + +支持：[rollup](https://github.com/rollup/rollup-plugin-node-resolve), [webpack](https://webpack.js.org/configuration/resolve/#resolve-mainfields) + +### `browser` + +```json +"browser": { + "module-a": "./shims/module-a.js", + "./server/only.js": "./shims/client-only.js" +} +``` + +字段由模块作者提供，作为 `JavaScript` 包或组件工具的提示，用于打包模块以供客户端使用。 提案就[在这里](https://github.com/defunctzombie/package-browser-field-spec)。 + +## 任务类字段 + +包里还可以包含一些可执行脚本或者其他配置信息。 + +### `scripts` + +```json +{ + "scripts": { + "build-project": "node build-project.js" + } +} +``` + +脚本是定义自动化开发相关任务的好方法，比如使用一些简单的构建过程或开发工具。 在 `scripts` 字段里定义的脚本，可以通过 `yarn run