fix(plugin-import-export): update docs on jobs and basic usage as well as visibility (#15695)

This PR adds more to the docs for how to use it as well as how to enable
and run jobs with it. Furthermore there are bug fixes as listed below,
some have necessitated some restructuring internally for how hooks are
included, now they are always run so that config can be dynamically read
from the collections.


Also does the following:
- Adds docs on jobs usage and example configuration
- Adds docs on jobs collection visibility, closes
#15591
- Fixes docs on basic example, closes
#15552
- Fixes a problem with per collection settings not being applied if
`overrideCollection` is not provided
- Fixes #15627

Author: paulpopus

docs/plugins/import-export.mdx

@@ -41,10 +41,10 @@ import { buildConfig } from 'payload'
 import { importExportPlugin } from '@payloadcms/plugin-import-export'
 
 const config = buildConfig({
-  collections: [Pages, Media],
+  collections: [Users, Pages],
   plugins: [
     importExportPlugin({
-      collections: ['users', 'pages'],
+      collections: [{ slug: 'users' }, { slug: 'pages' }],
       // see below for a list of available options
     }),
   ],
@@ -53,6 +53,51 @@ const config = buildConfig({
 export default config
 ```
 
+## Jobs Queue Requirements
+
+By default, the plugin uses Payload's [Jobs Queue](/docs/jobs-queue/overview) for import and export operations. Queued jobs require a runner to be configured, otherwise imports and exports will stay in "pending" status and never complete.
+
+Configure `jobs.autoRun` in your Payload config so that queued jobs are processed:
+
+```ts
+import { buildConfig } from 'payload'
+import { importExportPlugin } from '@payloadcms/plugin-import-export'
+
+const config = buildConfig({
+  collections: [Users, Pages],
+  jobs: {
+    autoRun: [
+      {
+        cron: '*/5 * * * *', // Check every 5 minutes
+        queue: 'default',
+      },
+    ],
+  },
+  plugins: [
+    importExportPlugin({
+      collections: [{ slug: 'users' }, { slug: 'pages' }],
+    }),
+  ],
+})
+
+export default config
+```
+
+Alternatively, use `allQueues: true` to process jobs from all queues:
+
+```ts
+jobs: {
+  autoRun: [
+    {
+      allQueues: true,
+      cron: '*/5 * * * *',
+    },
+  ],
+},
+```
+
+For smaller datasets or testing, you can run imports and exports synchronously by setting `disableJobsQueue: true` in the per-collection [ExportConfig](#exportconfig-options) or [ImportConfig](#importconfig-options). This avoids the need for a jobs runner but blocks the request until the operation completes.
+
 ## Options
 
 | Property                   | Type             | Description                                                                                                                 |
@@ -144,6 +189,34 @@ export default buildConfig({
 })
 ```
 
+## Collection Visibility
+
+The `exports` and `imports` collections are hidden from the admin navigation by default (`admin.group: false`). Their routes remain accessible (for example `/admin/collections/exports` and `/admin/collections/imports`), so you can open them directly or link to them from your app. To list them in the sidebar, use `overrideExportCollection` and `overrideImportCollection` to set a `group`:
+
+```ts
+import { importExportPlugin } from '@payloadcms/plugin-import-export'
+
+importExportPlugin({
+  overrideExportCollection: ({ collection }) => ({
+    ...collection,
+    admin: {
+      ...collection.admin,
+      group: 'Data Management',
+    },
+  }),
+  overrideImportCollection: ({ collection }) => ({
+    ...collection,
+    admin: {
+      ...collection.admin,
+      group: 'Data Management',
+    },
+  }),
+  collections: [{ slug: 'pages' }],
+})
+```
+
+With a group set, the Exports and Imports collections appear in the admin navigation under "Data Management", and you can open saved exports or import documents from there (including downloading saved export files).
+
 ## Limiting Import and Export Size
 
 You can limit the number of documents that can be imported or exported in a single operation. This helps prevent DDOS-style abuse and protects server resources during large data operations.
@@ -432,7 +505,12 @@ There are four possible ways that the plugin allows for exporting documents, the
 3. Local API - A create call to the uploads collection: `payload.create({ slug: 'uploads', ...parameters })`
 4. Jobs Queue - `payload.jobs.queue({ task: 'createCollectionExport', input: parameters })`
 
-By default, a user can use the Export drawer to create a file download by choosing `Save` or stream a downloadable file directly without persisting it by using the `Download` button. Either option can be disabled to provide the export experience you desire for your use-case.
+In the Export drawer you can choose:
+
+- **Download** — Streams the export file directly to the browser without saving. Nothing is stored in the exports collection.
+- **Save** — Creates a document in the exports collection (an upload) so the export is stored and can be reused or downloaded later.
+
+To download a saved export, open the exports collection (go to `/admin/collections/exports` or, if you made it visible as in [Collection Visibility](#collection-visibility), use the sidebar), open the export document, and use the file download from there. Either the Download or Save option can be disabled per collection via [ExportConfig](#exportconfig-options) (`disableDownload`, `disableSave`).
 
 The UI for creating exports provides options so that users can be selective about which documents to include and also which columns or fields to include.
 

packages/plugin-import-export/src/components/ExportSaveButton/index.tsx

@@ -6,6 +6,7 @@ import {
   toast,
   Translation,
   useConfig,
+  useField,
   useForm,
   useFormModified,
   useTranslation,
@@ -30,11 +31,19 @@ export const ExportSaveButton: React.FC = () => {
   const { getData, setModified } = useForm()
   const modified = useFormModified()
 
+  const { value: targetCollectionSlug } = useField<string>({ path: 'collectionSlug' })
+
+  const targetCollectionConfig = getEntityConfig({ collectionSlug: targetCollectionSlug })
+  const targetPluginConfig = targetCollectionConfig?.admin?.custom?.['plugin-import-export']
+
   const exportsCollectionConfig = getEntityConfig({ collectionSlug: 'exports' })
 
-  const disableSave = exportsCollectionConfig?.admin?.custom?.disableSave === true
+  const disableSave =
+    targetPluginConfig?.disableSave ?? exportsCollectionConfig?.admin?.custom?.disableSave === true
 
-  const disableDownload = exportsCollectionConfig?.admin?.custom?.disableDownload === true
+  const disableDownload =
+    targetPluginConfig?.disableDownload ??
+    exportsCollectionConfig?.admin?.custom?.disableDownload === true
 
   const label = t('general:save')
 
@@ -43,7 +52,7 @@ export const ExportSaveButton: React.FC = () => {
     let toastID: null | number | string = null
 
     try {
-      setModified(false) // Reset modified state
+      setModified(false)
       const data = getData()
 
       // Set a timeout to show toast if the request takes longer than 200ms
@@ -68,12 +77,10 @@ export const ExportSaveButton: React.FC = () => {
         },
       )
 
-      // Clear the timeout if fetch completes quickly
       if (timeoutID) {
         clearTimeout(timeoutID)
       }
 
-      // Dismiss the toast if it was shown
       if (toastID) {
         toast.dismiss(toastID)
       }

packages/plugin-import-export/src/components/FormatField/index.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+import type { ReactSelectOption } from '@payloadcms/ui'
+import type { SelectFieldClientComponent } from 'payload'
+
+import { FieldLabel, ReactSelect, useConfig, useField } from '@payloadcms/ui'
+import React, { useCallback, useEffect, useMemo } from 'react'
+
+const baseClass = 'field-type select'
+
+type Format = 'csv' | 'json'
+
+const allOptions: ReactSelectOption[] = [
+  { label: 'CSV', value: 'csv' },
+  { label: 'JSON', value: 'json' },
+]
+
+export const FormatField: SelectFieldClientComponent = (props) => {
+  const { getEntityConfig } = useConfig()
+  const width = props.field.admin?.width
+
+  const { setValue, value: formatValue } = useField<Format>()
+  const { value: targetCollectionSlug } = useField<string>({ path: 'collectionSlug' })
+
+  const targetCollectionConfig = getEntityConfig({ collectionSlug: targetCollectionSlug })
+  const forcedFormat = targetCollectionConfig?.admin?.custom?.['plugin-import-export']
+    ?.exportFormat as Format | undefined
+
+  const options = useMemo<ReactSelectOption[]>(() => {
+    if (forcedFormat) {
+      return [{ label: forcedFormat.toUpperCase(), value: forcedFormat }]
+    }
+    return allOptions
+  }, [forcedFormat])
+
+  const selectedOption = useMemo<ReactSelectOption | undefined>(() => {
+    const effectiveValue = forcedFormat || formatValue || 'csv'
+    return options.find((o) => o.value === effectiveValue) ?? options[0]
+  }, [forcedFormat, formatValue, options])
+
+  useEffect(() => {
+    if (forcedFormat && formatValue !== forcedFormat) {
+      setValue(forcedFormat)
+    }
+  }, [forcedFormat, formatValue, setValue])
+
+  const handleChange = useCallback(
+    (selected: ReactSelectOption | ReactSelectOption[]) => {
+      if (forcedFormat) {
+        return
+      }
+      if (Array.isArray(selected)) {
+        setValue((selected[0]?.value as Format) ?? 'csv')
+      } else {
+        setValue((selected?.value as Format) ?? 'csv')
+      }
+    },
+    [forcedFormat, setValue],
+  )
+
+  const isReadOnly = Boolean(forcedFormat) || props.readOnly
+
+  return (
+    <div className={baseClass} style={{ width }}>
+      <FieldLabel label={props.field.label} path={props.path} />
+      <ReactSelect
+        className={'format-field'}
+        disabled={isReadOnly}
+        inputId={`field-${props.path.replace(/\./g, '__')}`}
+        isClearable={false}
+        isSearchable={false}
+        onChange={handleChange}
+        options={options}
+        value={selectedOption}
+      />
+    </div>
+  )
+}

packages/plugin-import-export/src/export/createExport.ts

@@ -80,8 +80,11 @@ export const createExport = async (args: CreateExportArgs) => {
 
   if (debug) {
     req.payload.logger.debug({
-      message: 'Starting export process with args:',
+      msg: '[createExport] Starting export process',
+      exportDocId: id,
+      exportName: nameArg,
       collectionSlug,
+      exportCollection,
       draft: draftsFromInput,
       fields,
       format,
@@ -513,22 +516,50 @@ export const createExport = async (args: CreateExportArgs) => {
     }
   } else {
     if (debug) {
-      req.payload.logger.debug(`Updating existing export with id: ${id}`)
+      req.payload.logger.debug({
+        msg: '[createExport] Updating export document with file',
+        exportDocId: id,
+        exportCollection,
+        fileName: name,
+        fileSize: buffer.length,
+        mimeType: isCSV ? 'text/csv' : 'application/json',
+      })
+    }
+    try {
+      await req.payload.update({
+        id,
+        collection: exportCollection,
+        data: {},
+        file: {
+          name,
+          data: buffer,
+          mimetype: isCSV ? 'text/csv' : 'application/json',
+          size: buffer.length,
+        },
+        // Override access only here so that we can be sure the export collection itself is updated as expected
+        overrideAccess: true,
+        req,
+      })
+    } catch (error) {
+      const errorDetails =
+        error instanceof Error
+          ? {
+              message: error.message,
+              name: error.name,
+              stack: error.stack,
+              // @ts-expect-error - data might exist on Payload errors
+              data: error.data,
+            }
+          : error
+      req.payload.logger.error({
+        msg: '[createExport] Failed to update export document with file',
+        err: errorDetails,
+        exportDocId: id,
+        exportCollection,
+        fileName: name,
+      })
+      throw error
     }
-    await req.payload.update({
-      id,
-      collection: exportCollection,
-      data: {},
-      file: {
-        name,
-        data: buffer,
-        mimetype: isCSV ? 'text/csv' : 'application/json',
-        size: buffer.length,
-      },
-      // Override access only here so that we can be sure the export collection itself is updated as expected
-      overrideAccess: true,
-      req,
-    })
   }
   if (debug) {
     req.payload.logger.debug('Export process completed successfully')