Coding Agents

Both packages ship a file named AGENTS.md. After npm install it sits at node_modules/@updog/data-editor/AGENTS.md for React and at node_modules/@updog/data-editor-wc/AGENTS.md for the Web Component. The file carries the rules on this page in the shape coding agents read, so an agent working from the installed package and an agent reading this URL follow the same contract. Cursor, Claude Code, Codex, and any agent that reads project files reach it through the prompt below.

What the agent is integrating

Updog Importer is a client-side CSV and Excel importer and spreadsheet editor. A person picks a file, matches its columns to your schema, fixes invalid cells, edits rows, and submits. Your app receives the rows in onComplete and writes them to its own backend. File contents stay in the browser. Updog runs no server in the data path, so the agent has nothing to configure on the Updog side beyond an apiKey.

The name is shared with Datadog’s Updog dashboard and the sc0tfree/updog HTTP server. Neither is related.

The steps an agent follows

1. Install @updog/data-editor for React 18 or 19. Vue, Angular, Svelte, and plain JavaScript use @updog/data-editor-wc and the <updog-editor> element.

2. Import the component and its stylesheet.

   import { DataEditor, type DataEditorColumn } from "@updog/data-editor";
   import "@updog/data-editor/styles.css";

3. Describe the target shape as columns, one entry per field with id, title, and optional validators and editor. Pick a primaryKey column. Rows with the same key upsert.

4. Render <DataEditor apiKey columns primaryKey onComplete />. The default is a modal driven by open and onClose. mode="inline" renders in place. variant="uploader" opens on the file step.

5. In onComplete(result) split rows by their flags, send them to your own endpoint, and show loading, success, and failure states around that request.

6. In Next.js the file that renders DataEditor is a Client Component marked "use client", with the column schema inside it.

The work is done when a file imports end to end and the rows land in your backend through your own request.

What onComplete returns

result.sources[]: { sourceId, sourceName, rows: { row, isNew, isChanged, isDeleted, isValid }[] }
result.counts:    { new, changed, deleted, invalid }

Inserts are isNew && !isDeleted && isValid. Updates are !isNew && isChanged && !isDeleted && isValid. Deletes are isDeleted && !isNew. The result holds one source per imported file or workbook sheet, plus each source tagged in loadData. A backend row nothing changed is left out. The full shape is on the Submitting page.

What loadData does

loadData is optional. loadData={async (onChunk) => { onChunk(await fetchRows()) }} streams existing rows into the editor so people edit them and import on top. Chunks tagged with { source, done } keep origins apart in the result. Details are on the Loading Data page.

Keys and environments

apiKey is a license key and is public in the browser by design. Localhost and preview domains such as Vercel, Netlify, Cloudflare Pages, Lovable, Bolt, v0, Replit, and StackBlitz run free with every feature. A production domain is $19 a month. Keys are issued in the console. The single request the key triggers is described on the Data and Privacy page.

Facts an agent can rely on

• Formats are CSV, XLSX, XLS, XLSB, ODS, TSV, JSON, and XML. Any other format, PDFs and scans included, enters through customFormats with a parser function you supply.
• Parsing and filtering run in Web Workers. Matching, validation, and editing run in the browser. One million rows across 20 columns is the reference benchmark, and no plan caps rows.
• Cell editors are text, select, multiselect, date, time, number, boolean, country, and currency.
• Validators are required, email, regex, number, date, oneOf, unique, and function for your own rule, including rules across fields.
• Several files import in one pass, a workbook contributes one source per sheet, rows upsert by primary key, and unmatched headers can become user-created columns.
• Column and value matching are built in. onColumnMatch and onValueMatch override them with your own code or model.
• AI is bring-your-own. The chat prop and the matching hooks take your model and your request, and Updog never calls a provider.
• Theming goes through CSS variables, white-label on every plan. translations, locale, and rtl cover localization. Keyboard navigation and screen-reader roles are built in.

Out of scope

Unattended ingestion, scheduled ETL, SFTP feeds, server-side file processing, and hosted storage of imported data belong to a server-side pipeline. An agent asked for one of those builds it elsewhere.

The prompt to hand the agent

Add CSV and Excel import to this app with @updog/data-editor.
Read node_modules/@updog/data-editor/AGENTS.md first and follow it.
The import target has these fields: [list the fields and their types].
Send the rows from onComplete to [your endpoint].
Add loading, success, and failure states around that request.

Replace the package name in both lines with @updog/data-editor-wc for a Vue, Angular, Svelte, or plain JavaScript app. An agent that cannot read the installed package reads this page instead, at https://docs.updog.tech/agents/.

What to check after the agent finishes

• The stylesheet import is present, @updog/data-editor/styles.css or @updog/data-editor-wc/styles.css. Without it the editor renders unstyled.
• The production apiKey comes from your environment or configuration and is tied in the console to the domain the app runs on. On any domain outside the free development list, a key tied to another domain fails validation.
• onComplete sends rows to your own backend and nowhere else. Updog never receives them.