@firebase/crashlytics

中文文档
0.2.0发布于 2026/11/17Apache-2.0TypeScriptESM + CJS近 30 天下载 131.5万

The Firebase Web Telemetry package of the Firebase JS SDK

原始使用文档
文档目录16 节
  1. As a private preview customer, your experience is incredibl…
  2. Table of Contents
  3. Agent Setup Prompt
  4. Step 1: Configure Firebase/Cloud Project
  5. Option 1: Using Firebase Console (Recommended)
  6. Option 2: Using Firebase CLI
  7. Step 2: Core SDK Installation & Initialization
  8. Install Packages
  9. Initialize Firebase App Singleton
  10. Step 3: Framework-Specific Setup Guides
  11. Step 4: Force an Initial Crash
  12. Verify the Crash in the Console
  13. Debugging with AI Agents
  14. MCP Tools ( crashlytics:connect )
  15. REST API & Web Browser Metadata
  16. Additional Configuration & References

Firebase Crashlytics for Web Apps - Setup Guide

[!IMPORTANT] Crashlytics for Web Apps is currently in Private Preview and available only for enrolled EAP (Early Access Program) customers. If you are not yet enrolled, please fill out the sign-up form to request access before configuring your application.

We’re excited for you to try out Crashlytics for your web app and share your feedback!

Crashlytics for Next.js, React, Angular, React Router, and TanStack Router apps includes client-side error reporting, de-minified stack traces, and a dedicated dashboard in the Firebase Crashlytics Console.

Crashlytics for web apps uses Cloud Logging for telemetry storage and Cloud Storage for sourcemap storage under the hood, which are paid products with a generous free tier. Learn more about Logging pricing and Storage pricing.

As a private preview customer, your experience is incredibly valuable to our team. Please submit bugs, API feedback, or feature requests directly to our team by emailing [email protected] or filling out this feedback form.

Table of Contents


Agent Setup Prompt

You can ask your coding agent to do everything for you! Use our sample prompt below to set up Crashlytics for your web app automatically.

When you copy this into your coding agent, make sure to do the following before running:

  1. Fill in the correct apiKey and appId for your web app in firebaseConfig, which can be found in the Firebase Console in Settings > General. Note: This assumes you already have a Firebase project created with a web app within.
  2. Point your coding agent to the GitHub README files in packages/crashlytics/.
I would like to set up the Crashlytics JS SDK to my app. My firebase app config is as follows:

const firebaseConfig = {
  apiKey: "<YOUR_FIREBASE_API_KEY>",
  authDomain: "YOUR_PROJECT_NAME.firebaseapp.com",
  projectId: "YOUR_PROJECT_NAME",
  storageBucket: "YOUR_PROJECT_NAME.firebasestorage.app",
  appId: "<YOUR_FIREBASE_APP_ID>"
};

Follow the instructions in the Firebase Crashlytics Web Setup Guide GitHub READMEs for setting up the Crashlytics Web SDK. Start with the Cloud Project Setup (using the Firebase CLI), initialize the SDK, and then follow the Setup Guide for my app’s framework to enable automatic error collection. Do not set up programmatic error capturing for this project. Replace any of the "<SOME_VARIABLE>" values in the instructions with the appropriate values based on my Firebase app config above. Also make sure to set up source map uploading for stack trace de-obfuscation. If you encounter any issues during the setup process, please ask me and I can assist you further. Ensure that you have the necessary permissions to access the Firebase project and that you have the Firebase CLI installed and configured on your machine, logged in as me (ask me to log in on your behalf).

Step 1: Configure Firebase/Cloud Project

Crashlytics for web leverages Google Cloud Logging, Error Reporting, and Storage under the hood. You can configure your project automatically using the Firebase Console (recommended) or the Firebase CLI (particularly useful when using coding agents).

[!NOTE] If you are coming from an existing Google Cloud project and have not previously used Firebase with that project, you must accept the Firebase Terms of Service in the Firebase Console before proceeding with project setup.

  1. Navigate to the Firebase Console Crashlytics page.
  2. Select your project.
  3. Click Set up and follow the steps in the console.

Option 2: Using Firebase CLI

If you prefer configuring your project via the terminal or using an AI coding agent, run the following command:

firebase crashlytics:setup <YOUR_FIREBASE_APP_ID> --project <YOUR_FIREBASE_PROJECT_ID>

[!NOTE] Prerequisites: Requires Firebase CLI v15.34.2 or later, Owner/Editor project permissions, and Blaze billing enabled. Authentication: Ensure you are authenticated and using the correct project:

firebase login
firebase use <YOUR_FIREBASE_PROJECT_ID>

Automated Setup: This command automatically enables the required Telemetry APIs (clienttelemetry.googleapis.com, firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, and firebasecrashlytics.googleapis.com), updates API key restrictions for clienttelemetry.googleapis.com (if restricted), provisions the firebase-telemetry Cloud Logging bucket and routing sink, configures telemetry settings for your web app, and optionally sets up email alerts for new and regressed issues.


Step 2: Core SDK Installation & Initialization

Before configuring framework-specific integrations, complete the core package installation and Firebase App singleton setup:

Install Packages

Install the Firebase JS SDK:

npm install firebase

Initialize Firebase App Singleton

Create a central configuration utility file (src/lib/firebase.ts) using the credentials found in the Firebase Console under Settings > General. Both manual trackers and framework interfaces leverage this initialized FirebaseApp instance.

// src/lib/firebase.ts
import { initializeApp, getApps, getApp } from 'firebase/app';

const firebaseConfig = {
  apiKey: "<YOUR_FIREBASE_API_KEY>",
  authDomain: "<YOUR_AUTH_DOMAIN>",
  projectId: "<YOUR_FIREBASE_PROJECT_ID>",
  storageBucket: "<YOUR_STORAGE_BUCKET>",
  messagingSenderId: "<YOUR_MESSAGING_SENDER_ID>",
  appId: "<YOUR_FIREBASE_APP_ID>"
};

// Guarantee singleton initialization
export const app = getApps().length === 0
  ? initializeApp(firebaseConfig)
  : getApp();

Step 3: Framework-Specific Setup Guides

[!IMPORTANT] Make sure you have completed Step 1 (Configure Firebase/Cloud Project) and Step 2 (Core SDK Installation & Initialization) above before proceeding to your framework's setup guide below!

Select the guide matching your application framework:


Step 4: Force an Initial Crash

To verify that your setup is working and that crashes are properly delivered to Firebase Crashlytics, you can force a test crash in your application.

To ensure the crash is triggered on demand (and doesn't block application startup or fail server-side builds), add the following line inside a user interaction handler (such as a button click handler or event listener) in your application:

throw new Error("Test Crash");

Verify the Crash in the Console

  1. Run your application and trigger the crash by performing the action (such as clicking the test button).
  2. Open the Firebase Console Crashlytics dashboard.
  3. Select your project to view the newly logged crash report.

[!NOTE] It may take a few minutes for new crash reports to appear in the Firebase Crashlytics console.


Debugging with AI Agents

AI coding agents can assist in diagnosing and resolving web crashes directly within your development environment.

MCP Tools (crashlytics:connect)

Crashlytics provides Model Context Protocol (MCP) tools that let agents query crash data—including issues, report groups, event payloads, and stack traces—without manual copy-pasting.

  • crashlytics:connect Prompt: A guided interactive workflow that prioritizes top issues, investigates de-obfuscated sourcemaps against your local codebase, and helps the agent draft fixes. Learn more in the Crashlytics AI assistance with MCP documentation.

REST API & Web Browser Metadata

You and your agents can also programmatically query the Firebase Crashlytics REST API.

Web error events and report groups expose browser-specific telemetry dimensions to help identify platform anomalies:

FieldDescriptionExample
browser.platformClient OS / platform architecture"macintosh", "windows", "linux"
user_agent.nameBrowser client application name"chrome", "firefox", "safari", "edge"
user_agent.versionMajor/minor version of the browser client"150"
user_agent.originalRaw User-Agent string from the client request"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."

Additional Configuration & References

For advanced usage options and project configuration details, consult the following guides:

版本与发布记录

@firebase/crashlytics 共发布 16 个版本,首次发布于 2026/05/27;过去 12 个月发布了 16 个版本。

版本发布日期距今
0.2.0latest2026/11/17今天
0.2.0-20261116185243next2026/11/17今天
0.1.0-eap-sql.a9a137e67eap-sql2026/11/124 天前
0.1.12026/11/125 天前
0.1.1-202611111654422026/11/125 天前
0.1.1-202611101940282026/11/116 天前

其他发布通道:eap-crashlytics → 0.0.1-eap-crashlytics.d474e7535,eap-sql → 0.1.0-eap-sql.a9a137e67,next → 0.2.0-20261116185243。

关于 @firebase/crashlytics 的常见问题

@firebase/crashlytics 是什么?

The Firebase Web Telemetry package of the Firebase JS SDK

如何安装 @firebase/crashlytics?

在项目目录运行 npm install @firebase/crashlytics,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@firebase/app(0.x)、@firebase/app-types(0.x)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 crashlytics-setconstants,可以用 npx crashlytics-setconstants 直接运行。

@firebase/crashlytics 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@firebase/crashlytics 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@firebase/crashlytics 可以商用吗?

@firebase/crashlytics 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@firebase/crashlytics 的下载量有多少?

根据 npm 官方下载统计,@firebase/crashlytics 在 2026/10/15 – 2026/11/13 这 30 天内被下载 1,315,378 次,日均约 43,846 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@firebase/crashlytics 还在维护吗?

最新版本 0.2.0 发布于 2026/11/17(今天);至今共发布 16 个版本,其中过去 12 个月发布了 16 个;首次发布于 2026/05/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。