Payload Import/Export (with Import support)

A drop‑in replacement for the official Payload Import/Export plugin that adds first‑class Import support while remaining API‑compatible with the core experience.

• Works with Payload v3
• Same UI entry points and behavior as the official plugin
• Adds Import alongside Export (CSV and JSON)
• Preview data before exporting via a built‑in REST endpoint
• Fully localized with built‑in translations

Why this package?

The official plugin focuses on exporting data. This package keeps the same ergonomics and admin UI integration, but also includes Import capabilities so you can round‑trip data between environments with minimal effort.

Installation

Install from npm and add to your Payload config. This package name is payload-import-export.

pnpm add payload-import-export
# or
npm i payload-import-export
# or
yarn add payload-import-export

Add the plugin to your payload.config.ts:

import { buildConfig } from 'payload'
import { importExportPlugin } from 'payload-import-export'

export default buildConfig({
  // ...your config
  plugins: [
    importExportPlugin({
      // Optional: limit to specific collections
      // collections: ['posts', 'users'],

      // Optional: force a format and hide the dropdown
      // format: 'csv', // or 'json'

      // Optional: control UI actions in the preview screen
      // disableDownload: false,
      // disableSave: false,

      // Optional: run exports synchronously (do not use the jobs queue)
      // disableJobsQueue: false,

      // Optional: enable debug logs
      // debug: false,
    }),
  ],
})

Features

• Export to CSV or JSON
• Import from CSV or JSON (drop‑in admin UI)
• Collection‑scoped controls automatically added to the list view
• Preview up to 10 docs before exporting
• Select specific fields to export
• Sort and filter using the standard Payload find options
• Disable export/import for specific fields using field‑level flags
• i18n: merges plugin translations into your config

How it integrates

When enabled, the plugin:

• Adds a hidden export utility collection to track saved exports
• Injects UI components into each collection’s list view menu
• Registers a provider to make Import/Export state available in the admin: payload-import-export/rsc#ImportExportProvider
• Registers a REST endpoint used by the preview UI: POST /api/preview-data

Preview endpoint

• Path: POST /api/preview-data
• Body:
  • collectionSlug: string (required)
  • format: csv | json
  • fields?: string[] (flattened accessors)
  • draft?: 'yes' | 'no'
  • limit?: number (preview clamps to a maximum of 10)
  • locale?: string
  • page?: number
  • sort?: Payload sort object
  • where?: Payload where object

The endpoint returns a small preview payload that the UI uses to render the table/CSV.

Import

Import runs from the same admin entry point as Export and is designed to be a drop‑in experience.

• Supported formats: CSV and JSON
• For CSV, headers must match flattened field accessors (e.g. title, author.id, blocks.0.text)
• Disabled fields (see below) are ignored during import
• Array and nested data are supported via flattened paths

Note: Import creates or updates documents according to your admin selection and mapping. Ensure your access control permits the chosen operation.

Disabling fields from Import/Export

Set admin.importExport.disable on a field to exclude it from both Import and Export. The plugin detects and hides these fields in the UI and removes them from JSON preview.

Example field config:

{
  name: 'secretNotes',
  type: 'text',
  admin: {
    importExport: { disable: true },
  },
}

Options

Provided via importExportPlugin({...}):

• collections?: string[]
  • Limit the plugin to specific collections. Defaults to all collections.
• format?: 'csv' | 'json'
  • Force a specific format and hide the format selector.
• disableDownload?: boolean
  • Hide the Download button in the preview UI.
• disableSave?: boolean
  • Hide the Save button in the preview UI.
• disableJobsQueue?: boolean
  • Run exports synchronously instead of using the jobs queue.
• debug?: boolean
  • Enable extra console logging.
• overrideExportCollection?: (collection) => collection
  • Modify the internal export collection before it’s added.

Usage in the Admin UI

• Go to any configured collection list
• Open the “More” menu and select “Import/Export”
• Choose JSON or CSV, pick fields, filters, sorting, etc.
• Preview the first page of results
• Download or Save the export, or switch to Import to upload data

i18n

This plugin ships with multiple languages and will merge its translations into your config.i18n.translations automatically.

Development (optional)

A minimal dev project lives under dev/ for local testing.

• Copy dev/.env.example to dev/.env and set your DATABASE_URI and PAYLOAD_SECRET
• Run pnpm dev and open http://localhost:3000

License

MIT