Firebase Crashlytics - Web Setup Guide
This guide details the setup and configuration of Firebase Crashlytics for web applications.
Important references:
- Refer to
skills/firebase-basics/references/web_setup.mdfor project creation, registering a web app, and initializing the core Firebase app. - Refer to the Get started with Firebase Crashlytics for Web guide for detailed configuration, architecture, and framework documentation.
Prerequisites
- Ensure the Firebase project and web app are set up (see
skills/firebase-basics/references/web_setup.md). - Firebase CLI: Requires version v15.35.0 or later, authenticated
(
firebase login), and project set (firebase use <PROJECT_ID>). - Permissions & Billing: Cloud project Owner or Editor role and Blaze (pay-as-you-go) billing enabled.
1. Configure Firebase / Cloud Project
Web Crashlytics leverages Cloud Logging and Cloud Storage under the hood. Use the Firebase CLI to onboard your project and web app:
npx -y firebase-tools@latest crashlytics:setup <YOUR_FIREBASE_APP_ID> --project <YOUR_FIREBASE_PROJECT_ID>This automated command enables the required Telemetry APIs, provisions the Cloud Logging bucket with Log Analytics enabled, configures routing sinks, and sets up alerts.
2. Install Packages & Initialize SDK
Install the Firebase package:
npm install firebase- Initialize Firebase: Set up your
FirebaseAppsingleton following Step 2: Add and initialize the SDK in your app andskills/firebase-basics/references/web_setup.md.
3. Framework-Specific Setup Guides
Refer to the framework-specific guide corresponding to your app:
- Next.js Setup Guide:
Wrap
<CrashlyticsRoutes>fromfirebase/crashlytics/next-navigationinside a Client Component ("use client"), then wrap your root App Router layout. - React Setup Guide:
Wrap root application components with
<FirebaseCrashlytics>fromfirebase/crashlytics/react. - React Router Setup Guide:
Replace React Router's
<Routes>container with<CrashlyticsRoutes>fromfirebase/crashlytics/react-routerfor parameterized path tracking. - TanStack Router Setup Guide:
Initialize with
getCrashlytics(app)and bind error logging indefaultOnCatchusingrecordError(). - Angular Setup Guide:
Add
provideCrashlytics(() => app)fromfirebase/crashlytics/angularto application providers inapp.config.ts.
4. Stack Trace De-obfuscation (Source Map Uploading)
To display de-minified stack traces in the Crashlytics console, upload production source maps using the Firebase CLI:
npx -y firebase-tools@latest crashlytics:sourcemap:upload \
--project <YOUR_FIREBASE_PROJECT_ID> \
--app <YOUR_FIREBASE_APP_ID> \
--debug <BUILD_OUTPUT_DIRECTORY>[!CAUTION] Ensure
.mapfiles are deleted or are not publicly accessible in your hosted app to avoid leaking source code.
Pass --clean flag to remove local source maps after uploading.
Reference: Get readable crash reports (Web).
5. Force a Test Crash & Verify
- Add an on-demand crash trigger inside a user action handler (e.g., a button
click):
<button onClick={() => { throw new Error("Test Crash"); }}>Trigger Test Crash</button> - Trigger the crash in the running web application.
- Verify in the Firebase Console:
- Navigate to
https://console.firebase.google.com/u/0/project/<YOUR_FIREBASE_PROJECT_ID>/crashlytics/app/web:<YOUR_FIREBASE_APP_ID>/issues - Alternatively, verify using the
get_reporttool if the Firebase MCP server is installed.
- Navigate to
- Remove the test crash code once verified.
Reference: Test your implementation (Web).
6. Debugging with AI Agents
AI coding agents can assist with investigating web crashes:
- MCP Tools (
crashlytics:connect): Guided workflow prompt to query issues, inspect de-obfuscated sourcemaps against local code, and draft fixes (see Crashlytics AI assistance with MCP). - REST API & Telemetry Metadata: Programmatically query issues via the
Firebase Crashlytics REST API
using web dimensions (
browser.platform,user_agent.*). See Web browser metadata.
7. Additional Configuration & References
Consult the official Crashlytics documentation for advanced configurations:
- Customize Crash Reports (Web):
- App Versioning:
Automate telemetry version tagging using the
crashlytics-setconstantsbuild script helper. - Programmatic Error Capturing:
Manually record handled errors with custom key/value metadata using
recordError(). - Force Flushing:
Flush in-memory buffered records immediately before page unload using
flush(). - Best Practices & Gotchas: Import guidelines and framework integration tips.
- App Versioning:
Automate telemetry version tagging using the
- Configuration Guide:
- Alerting:
Configure email alerts for new and regressed issues via Firebase Console,
CLI (
crashlyticsWebAlerts), or Cloud Monitoring. - Sampling:
Control Cloud Logging volume and costs via Console sampling slider, Firebase
Telemetry Admin API (
PATCH), or Cloud Logging exclusion filters. - Force 100% Sampling for Debugging:
Override sampling locally during development via
self.FIREBASE_TELEMETRY_DEBUG = true. - Enable/Disable Telemetry Collection:
Programmatically toggle collection with Telemetry Admin API
:enableand:disablemethods. - Log Schema: Field definitions and payload structures for Cloud Logging telemetry records.
- Alerting:
Configure email alerts for new and regressed issues via Firebase Console,
CLI (