@dasasian/firebase-structured-logger

Structured logging for both halves of a Firebase app.

Your web app crashed at app-4f2a.js:1:98432. This tells you it was Checkout.tsx:42 — in your own Google Cloud project, next to your backend logs. Nothing leaves.

What you get

• A minified stack becomes Checkout.tsx:42. Your source maps stay on your server and never reach the browser. Source maps
• Browser and backend logs are one stream. One query finds all that one user did: labels.userId="…". Labels
• You see the path to the error. The pages, the clicks and the open dialog go with each entry. Breadcrumbs
• Errors are grouped in Cloud Error Reporting. You add no second product. How it works
• A flood costs three entries and a count. Repeats are counted, not dropped. Volume
• Your coding agent reads the logs. fsl logs and two skills come with the package. fsl logs · Skills

Install

npm install @dasasian/firebase-structured-logger

Needs Node 22 or later.

Quick start

In the browser:

import { initLogger, setupGlobalErrorHandler } from '@dasasian/firebase-structured-logger/client'
import { getFunctions, httpsCallable } from 'firebase/functions'

export const logger = initLogger({
  appId: 'my-app',
  releaseId: import.meta.env.VITE_RELEASE_ID ?? 'dev',
  logFunction: httpsCallable(getFunctions(), 'logFrontendEvent'),
})

setupGlobalErrorHandler()

In your Cloud Functions:

import { onCall } from 'firebase-functions/v2/https'
import { initLogger, createClientLogFunction, withLogging } from '@dasasian/firebase-structured-logger/functions'

initLogger({ appId: 'my-app' })

export const logFrontendEvent = createClientLogFunction()

export const checkout = onCall(
  withLogging({ functionName: 'checkout' }, async (request) => {
    await chargeCard(request.data)
  }),
)

The handler holds no log code. What it throws is logged with functionName and the caller's userId, and thrown again.

The full setup, with source maps, is in Get started.

Say it once, where it happens

Logging is an aspect of your app, not a part of each function. You state each fact one time, in the place where it is true, and fsl puts it on every entry.

Where	You write	You get
At startup	setupGlobalErrorHandler()	Every uncaught error, with its stack resolved to your source.
Where the user signs in	logger.setUser(uid)	The user on every entry from then on.
On the button	data-fsl-action="apply_discount"	The click, as a step in the trail of any later error.
On the dialog	data-fsl-view="Attachment"	Every entry written while the dialog is open says so.
Around the handler	withLogging({ functionName: 'checkout' }, handler)	The function name and the caller's verified user id on every entry, and what the handler throws.

The two attributes need enableActions() and enableViews() once at startup. A function takes no logger and no context, and it has no try and catch for the sake of a log. See one function, before and after.

Docs

fsl.dasasian.com · Changelog

• Start: Home · Get started · How it works
• Set up: Source maps · React · Vue · Cloud Functions · Cloud Run
• Capture more: Breadcrumbs · Clicks and submits · Tabs and dialogs · Slow screens · Feedback · Attachments
• Find and read: Labels · fsl logs · Skills
• Check and fix: Doctor · Troubleshooting · · ·

For coding agents

backend/node_modules/.bin/fsl install-skills, run from the project root, adds /fsl-review and /fsl-logs to your project; use the folder where you installed the package in place of backend. Do not use npx fsl there: in a folder with no install, it runs another package with the same name. node_modules/@dasasian/firebase-structured-logger/CAPABILITIES.md says what an app can add. llms.txt lists every page.

License

MIT © Dasasian