arc-import-export

One-line import/export for every arc-cms admin table.

Drop one <script> tag into your CmsLayout and every admin page with a table instantly gets CSV, JSON, and XLSX import/export — with a 3-step preview wizard, upsert support, and a full audit history. Zero per-page code required.

Inspired by django-import-export.

Features

• Auto-activates on every <table> in the admin — no widget imports, no per-page code
• ↓ Export to CSV, JSON, or XLSX in one click
• ↑ Import with a 3-step wizard: Upload → Preview (dry-run with error highlighting) → Confirm
• Upsert support — update existing records by a unique field, create new ones
• Batched commits — 500-row batches keep memory flat on large datasets
• Full history at /admin/import-export — every import and export logged with row counts and errors
• Lazy XLSX — SheetJS only loads when an XLSX request is actually made; CSV/JSON have zero runtime deps
• Dark mode native — uses your site's --ui-* CSS variables automatically
• Override-friendly — works on customized/overridden admin pages too

Install

bun add @arc-language/arc-import-export

Setup (3 steps)

1. Register the package in your Arc project

In arc.config.json, add the server routes and schema:

{
  "serverRoutes": [
    "node_modules/@arc-language/arc-import-export/src/server/import-export.arc"
  ],
  "schemas": [
    "node_modules/@arc-language/arc-import-export/src/server/schemas/import-log.arc"
  ]
}

2. Add the script tag to CmsLayout

In site/cms/CmsLayout.arc, add one line after your existing scripts:

@raw '<script src="/arc-ie/bar.js" defer></script>'

If you installed arc-cms via arc cms init, this line is already there.

3. Create a config file

In your project root, create arc-import-export.config.js:

export default {
  resources: {
    users:  { fields: ['name', 'email', 'role'],           uniqueBy: 'email' },
    pages:  { fields: ['title', 'slug', 'published'],      uniqueBy: 'slug'  },
    groups: { fields: ['name', 'slug', 'description'],     uniqueBy: 'slug'  },
  }
}

That's it. Open /admin/users — the Import/Export toolbar appears above the table.

How it works

/admin/users
  ┌─────────────────────────────────────────────────────┐
  │ users              ↓ Export   ↑ Import   History ↗  │  ← auto-injected toolbar
  └─────────────────────────────────────────────────────┘
  ┌──────────────────────────────────────────────────────┐
  │ Name        Email              Role      Joined      │
  │ ...         ...                ...       ...         │  ← your existing table
  └──────────────────────────────────────────────────────┘

Import wizard

Step 1 Upload    →    Step 2 Preview           →    Step 3 Confirm
────────────────      ─────────────────────────     ────────────────
Drop file here        ✓ 138 valid · ✗ 4 errors      Import 138 records
CSV / JSON / XLSX     [table of first 20 rows]       Cancel
                      [error rows highlighted red]

Resource auto-detection

The toolbar infers the resource from the URL path:

| URL | Resource | |-----|---------| | /admin/users | users | | /admin/my-orders | my-orders | | /admin/products | products |

To override (e.g. on a page with a custom URL), add a data-ie-resource attribute anywhere on the page:

@raw '<div data-ie-resource="products" data-ie-fields="name,sku,price"></div>'

Or use the optional widget:

import ImportExportBar from "@arc-language/arc-import-export/src/widgets/ImportExportBar.arc"

ImportExportBar resource="products" fields="name,sku,price" uniqueBy="sku"

Config reference

// arc-import-export.config.js
export default {
  resources: {
    [resourceName]: {
      fields:   string[],  // fields allowed in import (required for import to be enabled)
      uniqueBy: string,    // optional: upsert key — update if exists, create if not
    }
  }
}

| Option | Type | Required | Description | |--------|------|----------|-------------| | fields | string[] | Yes (for import) | Column names that can be imported. Export uses all columns by default. | | uniqueBy | string | No | Field used for upsert on import. If omitted, always creates new records. |

If a resource is not in the config, Export still works (shows all columns) but the Import button is hidden.

API routes

All routes are mounted automatically when you add the server route to arc.config.json.

| Method | Path | Auth | Description | |--------|------|------|-------------| | GET | /arc-ie/bar.js | Public | The auto-detect script (~3 KB gzip) | | GET | /admin/api/ie/config | editor+ | Field config for a resource | | POST | /admin/api/ie/preview | editor+ | Parse file, return preview (no DB write) | | POST | /admin/api/ie/commit | editor+ | Commit import to database | | GET | /admin/api/ie/export | editor+ | Stream export file download | | GET | /admin/api/ie/logs | editor+ | List import/export history | | GET | /admin/api/ie/logs/:id | editor+ | Single log detail with errors |

Supported formats

| Format | Import | Export | Notes | |--------|--------|--------|-------| | CSV | ✓ | ✓ | RFC 4180, handles quoted fields and escaped commas | | JSON | ✓ | ✓ | Array of objects; rows/data wrapper accepted on import | | XLSX | ✓ | ✓ | SheetJS (lazy-loaded — zero cost if unused) |

History page

Every import and export is logged at /admin/import-export:

• Filter by action (import / export), status (success / partial / failed), or resource name
• Click any row to see full details including per-row error messages
• Counts: total rows, imported, skipped, errors

Performance

| Operation | Complexity | Notes | |-----------|------------|-------| | Preview parse | O(n) time, O(20) space | Only first 20 rows buffered for preview | | Import commit | O(n) time, O(500) space | 500-row batch loop | | Export (CSV/JSON) | O(n) time, O(1) space | Streaming response | | Export (XLSX) | O(n) time, O(n) space | SheetJS buffer — unavoidable | | Config fetch | O(1) | Cached 60 s per browser tab |

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

# Clone
git clone https://github.com/arc-language/arc-import-export.git
cd arc-import-export

# Install
bun install

# Run against an arc-cms project (set ARC_PROJECT_DIR)
ARC_PROJECT_DIR=../my-arc-project bun run dev

License

MIT © KCuppens