Debugging with Console

Connect your running app to dcupl Console for live inspection of lists, queries, and data flow.

Prerequisites

A working dcupl application
Access to dcupl Console

Install @dcupl/connect

npm install @dcupl/connect

yarn add @dcupl/connect

pnpm add @dcupl/connect

@dcupl/connect depends on exactly its own version of @dcupl/core and @dcupl/common: install it in the same version as @dcupl/core.

Connect your app

Add the connect module to your dcupl instance:

app.ts

import { Dcupl } from '@dcupl/core';
import { DcuplConnect } from '@dcupl/connect';

const dcupl = new Dcupl();
// ... your model and data setup

await dcupl.init();

// Connect to Console. Don't await init() in your startup path (see below)
const connect = new DcuplConnect({ dcuplInstance: dcupl });
connect.init().then((status) => console.log('dcupl Connect:', status.state)); // 'connected' | 'disconnected'

The connection is started from the Console: in your project, open Applications → Connect, enter your app's URL under Application Url and click Connect Application. The Console opens your app in a new browser window, and connect.init() connects to it (Connect only talks to the Console at https://console.dcupl.com). When the app is opened directly (it has no window.opener), init() resolves with state: 'disconnected' right away. When a page other than the Console's dcupl Connect page opened it (for example with window.open() or a link that keeps the opener), init() waits for an answer that never comes and its promise doesn't settle, so don't await it before your app starts.

What you can inspect

Once connected, the Console receives your app's models, data and events:

Event stream – every model added, data change and list created, updated or destroyed in your app, with its arguments and result. dcupl's internal $Dcupl… models are left out.
Data Explorer, Models and Quality Analyzer – work on the connected instance the way they do on an application you run in the Console.
Show in Data Explorer – opens any list your app created, with its current query.

Loader Insights stays disabled: the Console didn't load the app from a dcupl.lc.json, so it has no loader run to show.

Development only

Disable the connect module in production. import.meta.env.DEV is Vite's flag; with other build tools, check process.env.NODE_ENV !== 'production':

app.ts

if (import.meta.env.DEV) {
  const connect = new DcuplConnect({ dcuplInstance: dcupl });
  connect.init();
}

Call connect.destroy() when you tear the dcupl instance down, for example on hot module replacement, so Connect stops listening to your app and stops sending its events and URL changes to the Console. Calling it before a connection is safe.