Import & Export - Vextro Docs

Vextro provides import and export utilities for moving collection data in and out of Convex. Supported formats are CSV and JSON. The system includes schema validation and detailed error reporting.

Exporting data

import { generateCsv } from "vextro/import-export";

const rows = documents.map((doc) => ({
  title: doc.title,
  slug: doc.slug,
  status: doc.status,
}));

const csv = generateCsv(rows);

CSV generation options

Option	Type	Default	Description
`delimiter`	`string`	`","`	Field delimiter character.
`quoteAll`	`boolean`	`false`	Quote all fields, not just those requiring it.
`includeBom`	`boolean`	`true`	Include UTF-8 BOM for Excel compatibility.

Importing data

Parse a CSV file and validate against the collection schema:

import { parseCsv, validateImportDocuments } from "vextro/import-export";

const { headers, rows } = parseCsv(fileContent);

const result = validateImportDocuments(rows, collectionFields, {
  requireAllFields: true,
  allowUnknownFields: false,
});
// result.valid    - documents ready to insert
// result.invalid  - documents with errors (row number, error details)
// result.warnings - non-blocking issues (unknown fields stripped)

Validation checks

Check	Description
Required fields	Non-optional fields must have a non-empty value.
Type correctness	Values must match expected types (string, number, boolean).
Value constraints	Numbers checked against `min`/`max`; strings against `maxLength`.
Enum values	Select and radio fields must contain a valid option.
Slug uniqueness	Duplicate slugs within the import set are flagged.
Unknown fields	Fields not in the schema generate warnings and are stripped.

Validation options

Option	Type	Default	Description
`requireAllFields`	`boolean`	`true`	Require all non-optional fields.
`allowUnknownFields`	`boolean`	`false`	Keep fields not in the schema.

Error reporting

Each invalid document includes its row number and a list of field errors:

{
  row: 3,
  document: { title: "", slug: "hello", status: "invalid" },
  errors: [
    { field: "title", message: 'Required field "Title" is empty', value: "" },
    { field: "status", message: 'Invalid value "invalid"', value: "invalid" },
  ],
}