Quickstart

This guide takes you from a brand-new account to your first captured bug report in the dashboard. It's the fastest complete path through BugPort: create a workspace and project, mint a widget key, install a capture method, submit a bug, and triage it. Plan on about ten minutes.

By the end you'll have a working reporting setup and a real report you can share or hand off.

FIRST RUN

Before you start

You'll move faster if you have these ready:

A way to sign in: a Google or GitHub account, or an email address for email/password sign-up. Authentication is handled by Supabase Auth.
The origin(s) where your app runs — for example http://localhost:3000 for local development and https://app.yourcompany.com for production. You'll add these to your widget key.
If you're embedding the widget: a React 18+ app and somewhere to mount a client-side component.
If you're using the browser extension instead: Google Chrome.

💡

You don't need a credit card to start. The Free plan includes 1 GB of storage and, like every plan, unlimited team members — so you can invite your whole team during setup at no extra cost.

Set up your account and first report

Create your account
Open the BugPort dashboard and sign in with Google, GitHub, or email/password. New accounts go through a short onboarding step that creates your first workspace automatically.
A workspace is the top-level container for your team, projects, billing, and storage. You can rename it later.
Create a project
Inside your workspace, create a project. A project is where related bugs live — usually one app or product surface. Most teams start with a single project and add more as they grow.
Projects are also the scope for widget keys, which you'll create next.
Create a widget key
Open your project's Widget keys and create a key. You'll get a public key that looks like bp_pub_….
Set the key's environment (for example local, staging, or production) and add the allowed origins that are permitted to submit with it — for example http://localhost:3000. Origin restriction is what makes a public key safe to ship in client code.
Copy the key somewhere handy; you'll paste it into your capture method.
Install a capture method
Choose how you'll capture bugs. You can use either (or both):
- NPM widget — embed @bugport.dev/widget in your React app so users report from inside the product. Pass your bp_pub_… key as projectKey. See NPM widget.
- Browser extension — install the Chrome extension, sign in, and pin it. It captures the deepest context (console, network with response bodies, page context, optional replay) on any page. See Browser extension.
For an in-product feedback flow, start with the widget. For internal QA and engineering reproduction, start with the extension.
Submit your first bug
Trigger a report:
- Widget: open your app on an allowed origin, open the widget, write a short note, optionally annotate or screenshot, and submit.
- Extension: open it on any page, start capture, reproduce the issue, annotate, add details, and submit.
On success the report is created and (for the widget) the onSubmitted callback receives a result containing the dashboard URL.
Review it in the dashboard
Open the dashboard and find your new bug. It carries a source badge (Widget or Plugin), the screenshot and annotations, console logs, any captured network requests and response bodies, and the page path it came from. Set a status and severity, and add a comment if you want.
Share or triage
Decide what happens next:
- Share a read-only public link so anyone — including people outside your workspace — can view the report without signing in.
- Triage in place: assign status/severity, discuss in comments, and follow the activity timeline. Exporting a bug to an issue tracker (GitHub Issues / GitLab) is In progress.

Setup checklist

Use this to confirm you're fully set up:

Signed in and onboarding created my first workspace
Created a project
Created a widget key (bp_pub_…) for the right environment
Added my app's origin(s) to the key's allowed origins
Installed a capture method (widget and/or extension)
Submitted a test bug
Saw the bug appear in the dashboard with its source badge
Set status and severity, and tried a share link

Common setup mistakes

A few issues catch almost everyone on the first run:

Origin not allowed (403)

A widget submission returns a 403/origin error when the page's origin isn't in the key's allowed origins. Add the exact origin (scheme + host + port, e.g. http://localhost:3000) to the key.

Wrong apiBaseUrl (404)

A 404 usually means apiBaseUrl is wrong. It must end in /v1 — the default is https://api.bugport.dev/v1. Only override it for local or self-hosted setups, and keep the /v1 suffix.

Widget renders nothing

If nothing appears, confirm you're on React 18+ and that the widget is mounted client-side (not server-rendered only).

Social login redirect

If Google/GitHub sign-in fails to return you to the app, the provider must be enabled in Supabase and the redirect allowlist must include your origin's /auth/callback.