firebase-tools 15.34.2 → 15.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/lib/api.js +2 -4
  2. package/lib/appcheck/debugTokens.js +293 -0
  3. package/lib/appcheck/localConfig.js +191 -0
  4. package/lib/appdistribution/options-parser-util.js +1 -1
  5. package/lib/apphosting/constants.js +1 -4
  6. package/lib/apphosting/githubConnections.js +1 -1
  7. package/lib/apphosting/utils.js +0 -26
  8. package/lib/auth.js +8 -2
  9. package/lib/commands/appcheck-debugtokens-create.js +60 -35
  10. package/lib/commands/appcheck-debugtokens-delete.js +21 -7
  11. package/lib/commands/appcheck-debugtokens-list.js +37 -8
  12. package/lib/commands/appcheck-debugtokens-prune.js +59 -0
  13. package/lib/commands/crashlytics-heapdumps-status.js +1 -1
  14. package/lib/commands/{crashlytics-onboard-web.js → crashlytics-setup.js} +5 -5
  15. package/lib/commands/crashlytics-sourcemap-upload.js +4 -0
  16. package/lib/commands/deploy.js +1 -3
  17. package/lib/commands/emulators-start.js +2 -2
  18. package/lib/commands/hosting-channel-create.js +1 -3
  19. package/lib/commands/hosting-channel-delete.js +1 -3
  20. package/lib/commands/hosting-channel-deploy.js +1 -3
  21. package/lib/commands/hosting-channel-list.js +1 -3
  22. package/lib/commands/hosting-channel-open.js +1 -3
  23. package/lib/commands/hosting-clone.js +3 -5
  24. package/lib/commands/hosting-disable.js +2 -2
  25. package/lib/commands/hosting-sites-create.js +1 -3
  26. package/lib/commands/hosting-sites-delete.js +1 -3
  27. package/lib/commands/hosting-sites-get.js +1 -3
  28. package/lib/commands/hosting-sites-list.js +1 -3
  29. package/lib/commands/index.js +4 -2
  30. package/lib/commands/run-services-get.js +19 -0
  31. package/lib/commands/run-services-list.js +11 -0
  32. package/lib/crashlytics/alerts.js +1 -0
  33. package/lib/crashlytics/events.js +122 -1
  34. package/lib/crashlytics/filters.js +12 -6
  35. package/lib/crashlytics/firebasetelemetry.js +5 -3
  36. package/lib/crashlytics/onboarding.js +8 -7
  37. package/lib/crashlytics/profilingManager.js +14 -34
  38. package/lib/crashlytics/reports.js +46 -17
  39. package/lib/crashlytics/sourcemap.js +19 -5
  40. package/lib/crashlytics/utils.js +14 -0
  41. package/lib/database/import.js +5 -4
  42. package/lib/dataconnect/dataplaneClient.js +0 -10
  43. package/lib/dataconnect/names.js +3 -3
  44. package/lib/dataconnect/schemaMigration.js +1 -1
  45. package/lib/deploy/apphosting/deploy.js +20 -41
  46. package/lib/deploy/apphosting/localBuild.js +49 -0
  47. package/lib/deploy/apphosting/prepare.js +12 -25
  48. package/lib/deploy/apphosting/release.js +1 -1
  49. package/lib/deploy/apphosting/util.js +27 -4
  50. package/lib/deploy/functions/backend.js +0 -10
  51. package/lib/deploy/functions/cel.js +1 -1
  52. package/lib/deploy/functions/containerCleaner.js +1 -142
  53. package/lib/deploy/functions/functionsDeployHelper.js +0 -4
  54. package/lib/deploy/functions/release/reporter.js +0 -26
  55. package/lib/deploy/functions/runtimes/discovery/index.js +4 -1
  56. package/lib/deploy/functions/runtimes/discovery/v1alpha1.js +1 -1
  57. package/lib/deploy/functions/services/index.js +13 -11
  58. package/lib/deploy/functions/validate.js +1 -1
  59. package/lib/deploy/hosting/prepare.js +1 -3
  60. package/lib/deploy/lifecycleHooks.js +1 -1
  61. package/lib/deploy/run/deploy.js +26 -43
  62. package/lib/deploy/run/get.js +30 -0
  63. package/lib/deploy/run/list.js +38 -0
  64. package/lib/deploy/run/prereqs.js +0 -3
  65. package/lib/deploy/run/util.js +9 -0
  66. package/lib/emulator/auth/operations.js +2 -2
  67. package/lib/emulator/auth/server.js +4 -2
  68. package/lib/emulator/auth/widget_ui.js +1 -1
  69. package/lib/emulator/commandUtils.js +109 -24
  70. package/lib/emulator/databaseEmulator.js +16 -11
  71. package/lib/emulator/dataconnect/pgliteServer.js +31 -24
  72. package/lib/emulator/downloadableEmulatorInfo.json +24 -24
  73. package/lib/emulator/downloadableEmulators.js +45 -7
  74. package/lib/emulator/extensions/postinstall.js +6 -6
  75. package/lib/emulator/firestoreEmulator.js +21 -15
  76. package/lib/emulator/functionsEmulator.js +11 -7
  77. package/lib/emulator/functionsEmulatorRuntime.js +7 -2
  78. package/lib/emulator/hub.js +12 -8
  79. package/lib/emulator/shared/express.js +30 -0
  80. package/lib/emulator/storage/apis/firebase.js +11 -10
  81. package/lib/emulator/storage/apis/gcloud.js +21 -20
  82. package/lib/emulator/storage/files.js +1 -1
  83. package/lib/emulator/storage/rules/manager.js +15 -12
  84. package/lib/emulator/storage/rules/runtime.js +1 -0
  85. package/lib/emulator/storage/server.js +10 -5
  86. package/lib/extensions/extensionsApi.js +0 -8
  87. package/lib/extensions/extensionsHelper.js +3 -24
  88. package/lib/extensions/paramHelper.js +1 -1
  89. package/lib/extensions/provisioningHelper.js +1 -6
  90. package/lib/extensions/secretsUtils.js +0 -24
  91. package/lib/firestore/util.js +3 -3
  92. package/lib/frameworks/angular/utils.js +1 -1
  93. package/lib/frameworks/next/utils.js +1 -12
  94. package/lib/fsAsync.js +34 -20
  95. package/lib/functions/kits/install.js +233 -628
  96. package/lib/functions/kits/sources/directory.js +91 -0
  97. package/lib/functions/kits/sources/npm.js +324 -0
  98. package/lib/functions/kits/sources/types.js +12 -0
  99. package/lib/functionsConfig.js +0 -4
  100. package/lib/functionsShellCommandAction.js +1 -1
  101. package/lib/gcp/artifactregistry.js +0 -5
  102. package/lib/gcp/cloudfunctionsv2.js +0 -6
  103. package/lib/gcp/devConnect.js +2 -2
  104. package/lib/gcp/iam.js +0 -4
  105. package/lib/gcp/pubsub.js +0 -14
  106. package/lib/gcp/storage.js +2 -1
  107. package/lib/hosting/api.js +79 -0
  108. package/lib/hosting/proxy.js +4 -1
  109. package/lib/init/features/hosting/github.js +6 -4
  110. package/lib/init/features/hosting/index.js +4 -0
  111. package/lib/init/features/run.js +3 -7
  112. package/lib/mcp/apps/init/mcp-app.js +4 -1
  113. package/lib/mcp/index.js +8 -2
  114. package/lib/mcp/prompts/apptesting/run_test.js +3 -3
  115. package/lib/mcp/prompts/core/deploy.js +3 -3
  116. package/lib/mcp/resources/guides/crashlytics_reports.js +33 -71
  117. package/lib/mcp/resources/guides/init_ai.js +10 -10
  118. package/lib/mcp/tools/crashlytics/events.js +18 -93
  119. package/lib/mcp/tools/crashlytics/index.js +2 -0
  120. package/lib/mcp/tools/crashlytics/reports.js +26 -31
  121. package/lib/mcp/tools/crashlytics/setup.js +392 -0
  122. package/lib/tsconfig.compile.tsbuildinfo +1 -1
  123. package/lib/tsconfig.publish.tsbuildinfo +1 -1
  124. package/lib/utils.js +4 -10
  125. package/package.json +1 -2
  126. package/lib/deploy/hosting/args.js +0 -2
@@ -0,0 +1,392 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.setup = exports.SUPPORTED_FRAMEWORKS = void 0;
4
+ const zod_1 = require("zod");
5
+ const apps_1 = require("../../../management/apps");
6
+ const logger_1 = require("../../../logger");
7
+ const tool_1 = require("../../tool");
8
+ const util_1 = require("../../util");
9
+ const PLACEHOLDER_PROJECT_ID = "<YOUR_FIREBASE_PROJECT_ID>";
10
+ const PLACEHOLDER_APP_ID = "<YOUR_FIREBASE_APP_ID>";
11
+ const PLACEHOLDER_API_KEY = "<YOUR_FIREBASE_API_KEY>";
12
+ const PLACEHOLDER_AUTH_DOMAIN = "<YOUR_AUTH_DOMAIN>";
13
+ const PLACEHOLDER_STORAGE_BUCKET = "<YOUR_STORAGE_BUCKET>";
14
+ const PLACEHOLDER_MESSAGING_SENDER_ID = "<YOUR_MESSAGING_SENDER_ID>";
15
+ exports.SUPPORTED_FRAMEWORKS = [
16
+ "nextjs",
17
+ "react",
18
+ "react-router",
19
+ "tanstack",
20
+ "angular",
21
+ ];
22
+ const FrameworkSchema = zod_1.z
23
+ .enum(exports.SUPPORTED_FRAMEWORKS)
24
+ .optional()
25
+ .describe("The web framework used ('nextjs', 'react', 'react-router', 'tanstack', or 'angular'). If provided, framework-specific code snippets and instructions are returned.");
26
+ const FRAMEWORK_GUIDES = {
27
+ nextjs: `### Next.js Setup Guide
28
+
29
+ #### Option A: Next.js 15.3+ (Recommended: Client Instrumentation)
30
+ Next.js 15.3+ supports client instrumentation via \`instrumentation-client.ts\` (or \`.js\`). This runs in the browser before React hydration begins and automatically registers global error listeners.
31
+
32
+ Create \`src/instrumentation-client.ts\` (or in project root if not using a \`src/\` directory):
33
+ \`\`\`typescript
34
+ import { getCrashlytics } from 'firebase/crashlytics';
35
+ import { app } from './lib/firebase'; // Shared initialization script
36
+
37
+ getCrashlytics(app);
38
+ \`\`\`
39
+
40
+ #### Option B: Next.js < 15.3 (Client Component Wrapper)
41
+ For Next.js versions earlier than 15.3, \`layout.tsx\` is a Server Component. Create a Client Component (e.g., \`src/components/CrashlyticsProvider.tsx\`):
42
+ \`\`\`tsx
43
+ 'use client';
44
+
45
+ import React from 'react';
46
+ import { FirebaseCrashlytics } from 'firebase/crashlytics/react';
47
+ import { app } from '../lib/firebase'; // Shared initialization script
48
+
49
+ export function CrashlyticsProvider({ children }: { children: React.ReactNode }) {
50
+ return (
51
+ <FirebaseCrashlytics firebaseApp={app}>
52
+ {children}
53
+ </FirebaseCrashlytics>
54
+ );
55
+ }
56
+ \`\`\`
57
+
58
+ Then wrap your application tree in \`src/app/layout.tsx\`:
59
+ \`\`\`tsx
60
+ import { CrashlyticsProvider } from '../components/CrashlyticsProvider';
61
+
62
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
63
+ return (
64
+ <html lang="en">
65
+ <body>
66
+ <CrashlyticsProvider>
67
+ {children}
68
+ </CrashlyticsProvider>
69
+ </body>
70
+ </html>
71
+ );
72
+ }
73
+ \`\`\``,
74
+ react: `### React Setup Guide (without React Router)
75
+
76
+ Wrap your root application component (typically \`src/App.tsx\` or \`src/main.tsx\`) with \`<FirebaseCrashlytics>\`. It acts as the global window receiver, handling unhandled rejections and browser exceptions:
77
+
78
+ \`\`\`tsx
79
+ import React from 'react';
80
+ import { FirebaseCrashlytics } from 'firebase/crashlytics/react';
81
+ import { app } from './lib/firebase'; // Shared initialization script
82
+
83
+ export default function App() {
84
+ return (
85
+ <FirebaseCrashlytics firebaseApp={app}>
86
+ {/* Rest of your application components */}
87
+ </FirebaseCrashlytics>
88
+ );
89
+ }
90
+ \`\`\`
91
+
92
+ > **Note**: If you use custom error boundaries in your application, you can also record caught errors manually via \`recordError(getCrashlytics(app), error)\`.`,
93
+ "react-router": `### React Router (v6+) Setup Guide
94
+
95
+ If your application uses React Router (v6+), replace React Router's \`<Routes>\` component with \`<CrashlyticsRoutes>\`. This handles uncaught errors across routes and tracks errors using parameterized templates (e.g., \`/profile/:userId\`):
96
+
97
+ \`\`\`tsx
98
+ import React from 'react';
99
+ import { BrowserRouter, Route } from 'react-router-dom';
100
+ import { CrashlyticsRoutes } from 'firebase/crashlytics/react-router';
101
+ import { app } from './lib/firebase'; // Shared initialization script
102
+ import Home from './pages/Home';
103
+ import Profile from './pages/Profile';
104
+
105
+ export default function App() {
106
+ return (
107
+ <BrowserRouter>
108
+ <CrashlyticsRoutes firebaseApp={app}>
109
+ <Route path="/" element={<Home />} />
110
+ <Route path="/profile/:userId" element={<Profile />} />
111
+ </CrashlyticsRoutes>
112
+ </BrowserRouter>
113
+ );
114
+ }
115
+ \`\`\``,
116
+ tanstack: `### TanStack Router Setup Guide
117
+
118
+ Initialize Crashlytics with \`getCrashlytics(app)\` and pass errors from \`defaultOnCatch\` to \`recordError\`:
119
+
120
+ \`\`\`typescript
121
+ import { recordError, getCrashlytics } from 'firebase/crashlytics';
122
+ import { app } from './lib/firebase'; // Shared initialization script
123
+ import { createRouter } from '@tanstack/react-router';
124
+ import { routeTree } from './routeTree.gen';
125
+
126
+ const crashlytics = getCrashlytics(app);
127
+
128
+ const router = createRouter({
129
+ routeTree,
130
+ defaultOnCatch: (error, errorInfo) => {
131
+ recordError(crashlytics, error, errorInfo);
132
+ },
133
+ });
134
+ \`\`\`
135
+
136
+ > **Tip**: Calling \`getCrashlytics(app)\` automatically registers global listeners for uncaught window errors and unhandled promise rejections, while \`defaultOnCatch\` captures errors caught during routing and rendering.`,
137
+ angular: `### Angular Setup Guide
138
+
139
+ Integrate with Angular's global error-catching runtime and route tracking by adding \`provideCrashlytics(() => app)\` to your application's providers in \`src/app/app.config.ts\`:
140
+
141
+ \`\`\`typescript
142
+ import { ApplicationConfig } from '@angular/core';
143
+ import { provideRouter } from '@angular/router';
144
+ import { provideCrashlytics } from 'firebase/crashlytics/angular';
145
+ import { app } from '../lib/firebase'; // Shared initialization script
146
+ import { routes } from './app.routes';
147
+
148
+ export const appConfig: ApplicationConfig = {
149
+ providers: [
150
+ provideRouter(routes),
151
+ provideCrashlytics(() => app),
152
+ ],
153
+ };
154
+ \`\`\`
155
+
156
+ > \`provideCrashlytics()\` registers a custom \`ErrorHandler\` to track uncaught zone crashes and uses internal \`Router\` instances to build dynamic routes rather than logging literal URLs.`,
157
+ };
158
+ function getFrameworkSection(framework) {
159
+ if (framework && framework in FRAMEWORK_GUIDES) {
160
+ return FRAMEWORK_GUIDES[framework];
161
+ }
162
+ return exports.SUPPORTED_FRAMEWORKS.map((fw) => FRAMEWORK_GUIDES[fw]).join("\n\n---\n\n");
163
+ }
164
+ async function resolveWebConfig(appIdInput, projectId) {
165
+ let resolvedAppId = appIdInput;
166
+ let detectedAppsNote;
167
+ let appPlatform;
168
+ if (appIdInput) {
169
+ if (appIdInput.includes(":web:")) {
170
+ appPlatform = apps_1.AppPlatform.WEB;
171
+ }
172
+ else if (appIdInput.includes(":android:")) {
173
+ appPlatform = apps_1.AppPlatform.ANDROID;
174
+ }
175
+ else if (appIdInput.includes(":ios:")) {
176
+ appPlatform = apps_1.AppPlatform.IOS;
177
+ }
178
+ }
179
+ if (projectId) {
180
+ try {
181
+ const apps = await (0, apps_1.listFirebaseApps)(projectId, apps_1.AppPlatform.ANY);
182
+ if (appIdInput) {
183
+ const matchedApp = apps.find((a) => a.appId === appIdInput);
184
+ if (matchedApp) {
185
+ appPlatform = matchedApp.platform;
186
+ }
187
+ }
188
+ else {
189
+ const webApps = apps.filter((a) => a.platform === apps_1.AppPlatform.WEB || a.appId.includes(":web:"));
190
+ if (apps.length > 0 && webApps.length === 0) {
191
+ return {
192
+ error: `Crashlytics setup is currently only supported for Web apps. No Web apps found in project '${projectId}'. For Android and iOS, Crashlytics is configured directly in your app's build configuration (Gradle or CocoaPods/SPM).`,
193
+ };
194
+ }
195
+ if (webApps.length === 1) {
196
+ resolvedAppId = webApps[0].appId;
197
+ }
198
+ else if (webApps.length > 1) {
199
+ resolvedAppId = webApps[0].appId;
200
+ detectedAppsNote = `Multiple web apps found in project '${projectId}'. Defaulting to ${resolvedAppId} (${apps[0].displayName || "unnamed"}). Other detected web apps: ${apps
201
+ .slice(1)
202
+ .map((a) => `${a.appId} (${a.displayName || "unnamed"})`)
203
+ .join(", ")}.`;
204
+ }
205
+ }
206
+ }
207
+ catch (err) {
208
+ logger_1.logger.debug("Failed to list web apps for project:", err);
209
+ }
210
+ }
211
+ if (appIdInput &&
212
+ appPlatform &&
213
+ appPlatform !== apps_1.AppPlatform.WEB &&
214
+ !appIdInput.includes(":web:")) {
215
+ return {
216
+ error: `Crashlytics setup is currently only supported for Web apps. No setup steps needed for non-Web app: ${appIdInput}. For Android and iOS, Crashlytics is configured directly in your app's build configuration (Gradle or CocoaPods/SPM).`,
217
+ };
218
+ }
219
+ const effectiveProjectId = projectId || PLACEHOLDER_PROJECT_ID;
220
+ const finalAppId = resolvedAppId || PLACEHOLDER_APP_ID;
221
+ if (resolvedAppId && resolvedAppId !== PLACEHOLDER_APP_ID) {
222
+ try {
223
+ const sdkConfig = await (0, apps_1.getAppConfig)(resolvedAppId, apps_1.AppPlatform.WEB);
224
+ if ("apiKey" in sdkConfig) {
225
+ const resolvedProjectId = sdkConfig.projectId || projectId || PLACEHOLDER_PROJECT_ID;
226
+ return {
227
+ config: {
228
+ apiKey: sdkConfig.apiKey || PLACEHOLDER_API_KEY,
229
+ authDomain: sdkConfig.authDomain ||
230
+ (resolvedProjectId !== PLACEHOLDER_PROJECT_ID
231
+ ? `${resolvedProjectId}.firebaseapp.com`
232
+ : PLACEHOLDER_AUTH_DOMAIN),
233
+ projectId: resolvedProjectId,
234
+ storageBucket: sdkConfig.storageBucket ||
235
+ (resolvedProjectId !== PLACEHOLDER_PROJECT_ID
236
+ ? `${resolvedProjectId}.firebasestorage.app`
237
+ : PLACEHOLDER_STORAGE_BUCKET),
238
+ messagingSenderId: sdkConfig.messagingSenderId || PLACEHOLDER_MESSAGING_SENDER_ID,
239
+ appId: sdkConfig.appId || resolvedAppId,
240
+ },
241
+ detectedAppId: finalAppId,
242
+ detectedAppsNote,
243
+ };
244
+ }
245
+ }
246
+ catch (err) {
247
+ logger_1.logger.debug("Failed to get app config:", err);
248
+ }
249
+ }
250
+ return {
251
+ config: {
252
+ apiKey: PLACEHOLDER_API_KEY,
253
+ authDomain: effectiveProjectId !== PLACEHOLDER_PROJECT_ID
254
+ ? `${effectiveProjectId}.firebaseapp.com`
255
+ : PLACEHOLDER_AUTH_DOMAIN,
256
+ projectId: effectiveProjectId,
257
+ storageBucket: effectiveProjectId !== PLACEHOLDER_PROJECT_ID
258
+ ? `${effectiveProjectId}.firebasestorage.app`
259
+ : PLACEHOLDER_STORAGE_BUCKET,
260
+ messagingSenderId: PLACEHOLDER_MESSAGING_SENDER_ID,
261
+ appId: finalAppId,
262
+ },
263
+ detectedAppId: finalAppId,
264
+ detectedAppsNote,
265
+ };
266
+ }
267
+ exports.setup = (0, tool_1.tool)("crashlytics", {
268
+ name: "setup",
269
+ description: "Provides setup guides and onboarding instructions for integrating Firebase Crashlytics into web applications (Next.js, React, React Router, TanStack Router, Angular). Note: This tool only applies to Web apps; Crashlytics for iOS and Android is configured via native build tools (Gradle/CocoaPods/SPM). Includes Cloud project setup, API enablement, logging buckets and sinks, SDK initialization, framework-specific code snippets, sourcemap uploads, and test crash verification.",
270
+ humanReadableDescription: "Provide setup instructions and configuration guides for integrating Firebase Crashlytics into web applications. Note: Only applies to Web apps.",
271
+ inputSchema: zod_1.z.object({
272
+ appId: zod_1.z
273
+ .string()
274
+ .optional()
275
+ .describe("Firebase Web App ID (e.g. '1:1234567890:web:abcdef1234567890'). This tool only applies to Web apps. If omitted, the tool will attempt to detect a Web app from the active project."),
276
+ framework: FrameworkSchema,
277
+ }),
278
+ annotations: {
279
+ title: "Set up Crashlytics for Web",
280
+ readOnlyHint: true,
281
+ idempotentHint: true,
282
+ },
283
+ _meta: {
284
+ requiresProject: false,
285
+ requiresAuth: false,
286
+ },
287
+ isAvailable: async () => true,
288
+ }, async ({ appId: appIdInput, framework }, ctx) => {
289
+ const resolved = await resolveWebConfig(appIdInput, ctx.projectId);
290
+ if ("error" in resolved) {
291
+ return (0, util_1.mcpError)(resolved.error);
292
+ }
293
+ const { config, detectedAppId, detectedAppsNote } = resolved;
294
+ const effectiveProjectId = ctx.projectId || PLACEHOLDER_PROJECT_ID;
295
+ const frameworkSection = getFrameworkSection(framework);
296
+ const noteSection = detectedAppsNote ? `\n> **Note**: ${detectedAppsNote}\n` : "";
297
+ const content = `# Firebase Crashlytics for Web Apps - Setup Guide
298
+
299
+ > [!IMPORTANT]
300
+ Crashlytics setup via this tool only applies to **Web apps** (Next.js, React, Angular, React Router, and TanStack Router). Crashlytics for Android and iOS is configured directly via native build tools (Gradle, CocoaPods, Swift Package Manager).
301
+
302
+ Crashlytics for web apps uses Cloud Logging for telemetry storage and Cloud Storage for sourcemap storage under the hood.
303
+ ${noteSection}
304
+ ---
305
+
306
+ ## Step 1: Configure Firebase / Cloud Project
307
+
308
+ ### Option 1: Using Firebase Console (Recommended)
309
+ 1. Navigate to the [Firebase Console Crashlytics page](https://console.firebase.google.com/u/0/project/_/crashlytics).
310
+ 2. Select your project: \`${effectiveProjectId}\`.
311
+ 3. Click **Set up** and follow the steps in the console.
312
+
313
+ ### Option 2: Using Firebase CLI
314
+ Run the setup commands to enable Crashlytics:
315
+ \`\`\`bash
316
+ firebase crashlytics:setup ${detectedAppId} --project ${effectiveProjectId}
317
+ \`\`\`
318
+ > **Prerequisites**: Requires Firebase CLI v15.34.2+, Owner/Editor project permissions, and Blaze billing enabled.
319
+
320
+ ---
321
+
322
+ ## Step 2: Core SDK Installation & Initialization
323
+
324
+ ### 1. Install Packages
325
+ Install the core Firebase package:
326
+ \`\`\`bash
327
+ npm install firebase
328
+ \`\`\`
329
+
330
+ ### 2. Initialize Firebase App Singleton
331
+ Create a central configuration file (\`src/lib/firebase.ts\`):
332
+ \`\`\`typescript
333
+ // src/lib/firebase.ts
334
+ import { initializeApp, getApps, getApp } from 'firebase/app';
335
+
336
+ const firebaseConfig = {
337
+ apiKey: "${config.apiKey}",
338
+ authDomain: "${config.authDomain}",
339
+ projectId: "${config.projectId}",
340
+ storageBucket: "${config.storageBucket}",
341
+ messagingSenderId: "${config.messagingSenderId}",
342
+ appId: "${config.appId}"
343
+ };
344
+
345
+ // Guarantee singleton initialization
346
+ export const app = getApps().length === 0
347
+ ? initializeApp(firebaseConfig)
348
+ : getApp();
349
+ \`\`\`
350
+
351
+ ---
352
+
353
+ ## Step 3: Framework-Specific Setup Guide
354
+
355
+ ${frameworkSection}
356
+
357
+ ---
358
+
359
+ ## Step 4: Force an Initial Crash
360
+
361
+ To verify that crashes are properly delivered to Firebase Crashlytics, add a test error inside a user interaction handler (such as a button click):
362
+
363
+ \`\`\`typescript
364
+ throw new Error("Test Crash");
365
+ \`\`\`
366
+
367
+ 1. Run your web application and trigger the crash by clicking the button.
368
+ 2. Open the [Firebase Console Crashlytics dashboard](https://console.firebase.google.com/u/0/project/_/crashlytics).
369
+ 3. Select project \`${effectiveProjectId}\` to view the newly logged crash report (note: reports may take 1-3 minutes to appear).
370
+
371
+ ---
372
+
373
+ ## Step 5: Source Map Uploading (Stack Trace De-obfuscation)
374
+
375
+ Upload your build source maps so Crashlytics displays original filenames, functions, and line numbers:
376
+
377
+ \`\`\`bash
378
+ firebase crashlytics:sourcemap:upload [buildOutputFolder] --app ${detectedAppId} --project ${effectiveProjectId}
379
+ \`\`\`
380
+
381
+ Provide the \`--clean\` flag to delete local source maps after uploading.
382
+
383
+ ---
384
+
385
+ ## Additional Configuration
386
+
387
+ - **Force 100% Sampling for Debugging**: Set \`self.FIREBASE_TELEMETRY_DEBUG = true;\` in browser code or DevTools console to force 100% telemetry collection for the current session.
388
+ - **Session Sampling Rate**: Configure session sampling (0% to 100%) in the Firebase Console (**Configure sampling**) or via the Firebase Telemetry Admin API.
389
+ - **Alerting**: Configure email alerts for new and regressed issues in Firebase Console under **Project Settings > Alerts**.
390
+ `;
391
+ return (0, util_1.toContent)(content);
392
+ });