scarf-js

Scarf就像是npm包的Google Analytics。通过在安装后发送一些基本信息，这个包可以帮助你洞察你的包是如何被使用的以及被哪些公司使用。Scarf旨在帮助开源开发者在其作品被商业使用时获得资金支持。

要了解更多关于我们为什么编写这个库的原因，请查看关于这个主题的这篇文章。

特性

无依赖。
对用户完全透明。Scarf会在安装过程中将其行为记录到控制台。对于没有明确给予权限的用户，它绝不会悄悄地报告分析数据。
绝不会中断你的包安装过程。报告是在尽最大努力的基础上进行的。

安装

你首先需要在Scarf上创建一个库条目。创建完成后，在你自己的库中添加对这个库的依赖：

npm i --save @scarf/scarf

一旦你的库带有这个变更发布到npm上，Scarf将自动在安装时收集统计数据，无需额外的代码！

前往Scarf上你的包的仪表板查看可用的报告。

配置

你的包的用户默认会被选择加入，他们可以通过设置SCARF_ANALYTICS=false环境变量来选择退出。如果你希望Scarf分析默认为选择加入，你可以通过在你的package.json中添加一个条目来设置

// your-package/package.json

{
  // ...
  "scarfSettings": {
    "defaultOptIn": false
  }
  // ...
}

现在Scarf将默认为选择退出，用户可以设置SCARF_ANALYTICS=true来选择加入。

无论默认状态如何，Scarf都会向那些没有明确选择加入或退出的用户记录它正在做什么。

默认情况下，scarf-js只会在你的包作为另一个包的依赖安装时，或者正在全局安装时触发分析。这确保了scarf-js分析不会在你的项目内运行npm install时被触发。要改变这一点，你可以添加：

// your-package/package.json

{
  // ...
  "scarfSettings": {
    "allowTopLevel": true
  }
  // ...
}

完整配置示例

// your-package/package.json

{
  // ...
  "scarfSettings": {
    // 切换是否为此包启用Scarf
    "enabled": true,
    // 当用户直接在你的仓库中运行npm install时启用Scarf
    // 如果可以获取，Scarf将尝试报告你的仓库的Git提交SHA
    "allowTopLevel": true,
    // 用户默认将被选择加入分析
    "defaultOptIn": true,
    // 默认情况下，Scarf会在你的构建的依赖图中搜索自己的位置，以确保
    // 可以为所有使用Scarf的包进行报告。
    // 对于有大量依赖的大型项目，生成该依赖图所需的时间比Scarf为其
    // 整个过程分配的时间更长，所以Scarf总是会超时。`skipTraversal`
    // 是一个可选标志，用于大型应用完全跳过该遍历。使用此标志时要
    // 谨慎小心，因为它将破坏你的构建中所有其他依赖包的Scarf分析。
    "skipTraversal": false
  }
  // ...
}

FAQ

作为包作者，scarf-js为我提供了哪些信息？

了解你的用户群
- 哪些公司在使用你的包？
- 你的项目是在增长还是在缩小？在哪里？在哪些平台上？
你的包的哪些版本正在被使用？

作为使用scarf-js的包的用户，scarf-js会发送关于我的哪些信息？

Scarf不存储个人识别信息。 Scarf旨在收集对以下方面有帮助的信息：

开源包维护
开源商业化

具体来说，scarf-js发送：

你正在使用的操作系统
你的IP地址将用于查找任何可用的公司信息。Scarf不存储实际的IP地址
有限的依赖树信息。Scarf发送直接依赖scarf-js的包的名称和版本。此外，scarf-js将发送以下依赖树中包的SHA256哈希名称和版本：
- 依赖依赖scarf-js的包的包。
- 依赖树的根包。这允许Scarf为维护者提供关于哪些公共包正在使用他们自己的包的信息，而不暴露非公开包的识别细节。

你可以通过在环境中设置SCARF_VERBOSE=true来让scarf-js打印它发送的确切JSON负载。

作为使用scarf-js的包的用户，我如何选择退出分析？

Scarf的分析有助于支持你正在使用的开源包的开发者，所以启用分析是受欢迎的。但是，如果你想选择退出，你可以在你项目的package.json中添加你的偏好：

// your-package/package.json

{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

或者，你可以在你的环境中设置这个变量：

export SCARF_ANALYTICS=false

你也可以按照Console Do Not Track标准设置这个变量：

export DO_NOT_TRACK=1

以上任一方式都将为所有包禁用Scarf。

我在npm上分发一个包，scarf-js在我们的依赖树中。我可以为我的下游依赖禁用分析吗？

是的。通过在package.json中选择退出分析，任何上游包都将禁用分析。

// your-package/package.json

{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

你的包的安装者将对所有上游依赖禁用scarf-js。

开发

设置环境变量SCARF_LOCAL_PORT=8080将配置Scarf使用http://localhost:8080作为分析端点主机。

未来工作

scarf-js的未来版本将提供一个实用函数模块，用于收集使用分析，以补充当前的安装分析。

社区

加入Scarf-Community工作区的Slack，在#scarf-js频道找到我们。我们会关注你的问题和关切。