Docs

Apps built with Lovable, Bolt, v0 or Replit

Add Sypnia to an app made with an AI app builder, with the prompt to give the builder, the code it should produce, and how to check that it did it right.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The prompt
  2. In your builder
  3. Check that the builder did it right
  4. The app still works
  5. Sypnia receives it
  6. Ask the builder to confirm
  7. When Sypnia reports a problem

This guide is for people who built their app by describing it. You do not need to read code to follow it. It works with Sypnia Cloud and with a self-hosted engine; the examples use Sypnia Cloud, and one line changes for your own engine.

At the end you will have: Sypnia watching the app your builder made, so that when a button stops working after «one small change», you are told in a sentence, with a prompt you can paste straight back into the builder.

You need: a project in Sypnia and its ingest key, which starts with spk_. The Cloud quickstart creates both in its first step.

The prompt

Paste this into your builder’s chat, with your own key in place of the example. It is written so that the builder cannot get the important parts wrong.

Text
Add Sypnia monitoring to this app.

1. Install the npm package @sypnia/browser. (If this is a Next.js app, install
   @sypnia/next instead and follow https://docs.sypnia.com/sdks/nextjs.md.)
2. In the file where the app starts, before it renders, add:

   import { init } from '@sypnia/browser';

   init({
     project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
     environment: location.hostname === 'MY-REAL-DOMAIN.com' ? 'production' : 'development',
   });

   Replace MY-REAL-DOMAIN.com with the domain where my customers use the app.
3. Call init exactly once. Do not wrap it in a component or an effect.
4. Where the app knows who signed in, call
   identify({ person: { id: user.id } }) from '@sypnia/browser',
   and identify(null) on sign-out. Send the id only, no name or e-mail.
5. Do not add any other Sypnia call. Do not try to record what people type.
   The key above is public and belongs in the code; never add a key that starts with sps_.
6. Show me the files you changed.

Reference: https://docs.sypnia.com/llms.txt

On a self-hosted engine, add one line to the init call in the prompt: endpoint: 'https://sypnia.example.com', with your engine’s address.

Why the environment line matters: builders show your app in a preview while you work. Without that line, every test you make in the preview would count as a real customer and send you alerts.

In your builder

What follows is what we know to be stable about each tool: what kind of app it makes and where the code goes. Menus and names in these tools change often. Where a step depends on the tool’s own features, it says so: check the tool’s current documentation instead of trusting a menu name written here.

Lovable

Lovable makes React apps built with Vite.

  • Give it the prompt above. The init call belongs in src/main.tsx, before the line that renders the app.
  • If it asks where to keep the key: in the code is fine. The ingest key is public.
  • If your app uses Supabase (Lovable connects to it), also read Supabase apps: one more option records the calls to your database.
  • Check the result in the published app, not only in the preview. Whether you can open and edit the code yourself, or sync it to GitHub, depends on your plan: check Lovable’s current documentation.

Check that the builder did it right

You do not have to read the code. Check three things:

  1. The app still works

    Open the published app and use it as a customer would.

    You should see
    Everything behaves as before. Sypnia shows nothing on your pages.
  2. Sypnia receives it

    In Sypnia, open Sessions. Choose the environment production if you used your real domain, development if you used the preview.

    You should see
    Within 10 minutes, your own visit, with the pages you opened and what you clicked.
  3. Ask the builder to confirm

    Paste: «List every place where Sypnia is called in this app, and confirm that init is called once and that no key starting with sps_ is in the code.»

    You should see
    One init, at most one identify and one identify(null), and no sps_ key.

If no session appears, the most common causes with builders are an init placed inside a component (so it runs late or twice) and a preview address that does not match the environment line. Troubleshooting has the full list.

When Sypnia reports a problem

This is the part these tools make easy. Every problem comes with a prompt written for a coding agent: what happens, where, why, what to change and how to check it. Copy it from the problem and paste it into your builder’s chat. See The prompt.

Two honest limits:

  • File names in problems. Sypnia shows the file and line in your own code only if your build uploads its source maps. Whether you can add a build step depends on the builder; with a Next.js app on Vercel it is two environment variables (Next.js on Vercel). Without source maps the problem still says what happened, to whom and since when.
  • Pull requests Cloud need your code on GitHub and the Sypnia GitHub App. If your builder syncs to GitHub, that works; if not, use the prompt.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close