Developer docs

CONCH from install to live ecommerce preview.

This is the full working map: npm package setup, runtime monitoring, AI ecommerce builder, public storefront APIs, deployments, route protection, and production env setup.

SDKBuilderDeploymentsBackendProduction
NPM package

Install and initialize @mrdhanwani/conch.

The SDK is a small JavaScript runtime client. It works in browser apps and Node runtimes, uses fetch, and posts JSON events to your CONCH backend.

Install

Add the runtime SDK

Install the npm package in the frontend you want to monitor.

npm install @mrdhanwani/conch
Initialize

Point events at CONCH

Initialize once near your app root with an ingest endpoint and API key.

import { initConch } from "@mrdhanwani/conch";

initConch({
  apiKey: "conch_xxxxx",
  endpoint: "/api/ingest/event",
  appName: "storefront",
  environment: "production",
});
Capture

Send errors with context

Capture exceptions, messages, or custom events with metadata that helps explain what happened.

import { captureException } from "@mrdhanwani/conch";

captureException(error, {
  codeSnippet: "cart.items.map(renderLineItem)",
  metadata: { route: "/checkout" },
});

initConch(options)

Call this once when your app starts. It stores the API key, endpoint, app name, environment, release, default metadata, custom headers, and optional hooks.

initConch({
  apiKey: "conch_project_api_key",
  endpoint: "https://your-backend.com/api/ingest/event",
  appName: "checkout-web",
  environment: "production",
  release: "1.3.0",
  metadata: { team: "growth", region: "in" },
  headers: { "X-App-Version": "1.3.0" },
  beforeSend(payload) {
    return payload.errorMessage?.includes("ResizeObserver") ? null : payload;
  },
  onError(error) {
    console.error("CONCH failed to report", error);
  },
});

captureException(error, context)

Use this for real Error objects. CONCH keeps the name, message, stack trace, optional code snippet, and runtime metadata.

try {
  await checkout();
} catch (error) {
  captureException(error, {
    codeSnippet: "await checkout()",
    metadata: { route: "/checkout", cartId: cart.id },
  });
}

captureMessage(message, context)

Use this for warnings, failed states, or non-Error cases where you still want an incident trail.

captureMessage("Payment gateway returned an empty response", {
  metadata: {
    route: "/checkout",
    gateway: "stripe",
  },
});

captureEvent(event)

Use this when you already have a normalized payload from another logger or custom error boundary.

captureEvent({
  errorName: "HydrationError",
  errorMessage: "Client and server markup did not match",
  stackTrace: stack,
  codeSnippet: "render(<App />)",
  metadata: { route: window.location.pathname },
});

getConchConfig()

Use this for debugging integration setup. It does not reveal the API key, only whether one exists.

const config = getConchConfig();

console.log(config);
// {
//   initialized: true,
//   endpoint: "...",
//   appName: "checkout-web",
//   environment: "production",
//   release: "1.3.0",
//   hasApiKey: true
// }
Builder

The website builder is ecommerce-first right now.

CONCH is not trying to generate every possible website category today. The supported builder lane is ecommerce: stores, catalogs, product pages, cart interactions, saved products, and customer capture.

Website builder

The builder turns a prompt and optional logo into an ecommerce-style site draft. It creates pages, navigation, hero copy, sections, product-like cards, catalog categories, cart controls, favourite actions, and a customer capture form.

  • Currently supported: ecommerce storefronts, catalogs, product-focused landing pages, carts, favourites, customer leads, and checkout-ready sections.
  • Not the current focus: blogs, portfolios, SaaS docs, marketplaces, social apps, or custom app logic outside ecommerce flows.
  • Logged-in users get a backend-linked store. Guests can still see a local preview, but data persistence needs login.

Ecommerce backend

When a generated draft is linked, CONCH creates a store record and product records. The public storefront API can then read products and write carts, favourites, and customer details.

  • Public store read: GET /api/ecommerce/public/stores/:storeIdOrSlug
  • Cart write: POST or PATCH /api/ecommerce/public/stores/:storeId/cart/items
  • Favourites write: POST /api/ecommerce/public/stores/:storeId/favourites/toggle
  • Customer lead: POST /api/ecommerce/public/stores/:storeId/customers
Deployments

Import repos, detect the stack, then publish a preview path.

The deployment area manages repository metadata and preview routing. For generated ecommerce stores, the public route can render the linked storefront with working cart, favourites, and lead capture.

Deployments

The deployment dashboard imports GitHub repositories, detects the stack, stores project settings, records deployment runs, and exposes path-based previews under /site/:slug.

  • Repository detection checks package.json, lockfiles, and index.html to choose Next.js, React/Vite, Node.js, or vanilla defaults.
  • Deployment settings include root directory, package manager, install command, build command, output directory, environment variables, and custom domain.
  • Public previews can show captured ecommerce storefronts when a matching generated store exists.
Backend contract

POST runtime events to /api/ingest/event.

The backend expects an API key in X-API-KEY or the request body. It stores the log against the matching project and queues analysis.

Ingest payload

Send at least an error message. Stack trace, code snippet, and metadata are optional but useful.

POST /api/ingest/event
X-API-KEY: conch_project_api_key
Content-Type: application/json

{
  "errorName": "TypeError",
  "errorMessage": "Cannot read properties of undefined",
  "stackTrace": "TypeError: ...",
  "codeSnippet": "user.name.toUpperCase()",
  "metadata": {
    "browser": "Chrome",
    "os": "Windows",
    "url": "https://example.com/checkout",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Runtime monitoring

The npm SDK sends runtime failures to the backend ingest route. The backend validates the project API key, stores the log, and queues AI analysis for root cause notes.

  • The SDK automatically captures browser window errors and unhandled promise rejections unless disabled.
  • Node uncaught exceptions and unhandled rejections are also supported when the SDK runs in Node.
  • Metadata is normalized into browser, OS, URL, and user agent fields for dashboard triage.
Production setup

Set these env vars before deploying.

Most production breakage comes from the browser calling localhost or the backend blocking the deployed origin. These are the env names that matter.

NEXT_PUBLIC_BACKEND_URLFrontend

Public backend origin used by browser API calls in production.

NEXT_PUBLIC_BASE_URLFrontend

Legacy public backend origin. Prefer NEXT_PUBLIC_BACKEND_URL now.

CLIENT_URLBackend

Comma-separated frontend origins allowed for credentialed CORS.

PUBLIC_APP_URLBackend

Base URL used to generate /site/:slug preview links.

PLATFORM_DOMAINBackend

Domain suffix used for reserved preview domains.

GEMINI_API_KEYBackend

Enables AI builder generation. Without it, the builder falls back to a local draft.

CLOUDINARY_*Backend

Required for product/logo image uploads.

Fast path

Build the store, deploy the preview, monitor runtime errors.

Start in the builder for ecommerce pages, use deployments for public preview links, and add the SDK to any JavaScript app you want to monitor.

Open builder