DatoCMS Project Exporter Plugin

A powerful DatoCMS plugin that allows you to export your project's records and assets directly from the dashboard. Whether you need a complete backup, a specific set of data for analysis, or just a single record, Project Exporter handles it with support for multiple popular formats.

Features

• Multiple Export Formats: Export your data in JSON, CSV, XML, or XLSX.
• Bulk Record Export: Download all records in your project.
• Filtered Exports:
  • By Model: Select specific models to export records from.
  • By Text Search: Export records matching a specific search query.
• Import-Friendly JSON Envelope: JSON exports include manifest, schema ID/API-key maps, projectConfiguration (site/settings resources), and a referenceIndex for records/uploads/blocks/structured-text links.
• Chunked Asset Export: Assets are split into conservative multi-ZIP chunks to reduce browser memory pressure.
• Asset Mapping Manifests: Every ZIP includes manifest.json and deterministic filename conventions for easier re-import.
• Single Record Export: JSON single-record exports use the same envelope shape as bulk JSON exports.

Installation

1. Go to your DatoCMS project dashboard.
2. Navigate to Settings > Plugins.
3. Click the Plus icon to add a new plugin.
4. Search for Project Exporter or install it manually using the package name datocms-plugin-project-exporter.

Configuration

Once installed, you can configure the default export format in the plugin settings:

1. Navigate to Settings > Plugins.
2. Click on Project Exporter.
3. In the configuration area (or via the plugin's main page), you can select your preferred default format:
   • JSON
   • CSV
   • XML
   • XLSX

Note: You can also change the format on-the-fly when performing an export.

Usage

Exporting Records (Bulk)

To perform bulk exports, navigate to the plugin's configuration screen (typically found under Settings > Plugins > Project Exporter > Config Screen or the dedicated plugin page if applicable).

1. Select Format: Choose between JSON, CSV, XML, or XLSX from the dropdown menu.
2. Filter by Model: Use the dropdown to select one or multiple models. Click "Download records from selected models" to export only those records.
3. Filter by Text: Enter a search term in the text field. Click "Download records from text query" to export matches.
4. Export All: Click "Download all records" to export everything.

Exporting Assets

1. On the main plugin screen, click the Download all assets button.
2. The plugin scans assets and creates one or more ZIP files using conservative limits.
3. Every ZIP includes:
   • Asset binaries
   • manifest.json with source upload IDs and metadata
4. ZIP entry filenames follow:
   • u_<sourceUploadId>__<sanitizedOriginalFilename>

Exporting a Single Record

When editing a specific record:

1. Look for the Record Downloader panel in the right sidebar.
2. Click Download this record.
3. The record will be downloaded in the format currently selected in the plugin's global configuration.

Development

This plugin is built with React and the DatoCMS Plugin SDK. To contribute or modify the plugin locally:

1. Clone the repository:

   1
   git clone https://github.com/marcelofinamorvieira/datocms-plugin-project-exporter.git

2. Install dependencies:

   1
   npm install
   2
   # or
   3
   pnpm install

3. Start the development server:

   1
   npm start

4. Follow the DatoCMS Plugin SDK documentation to link your local server to a DatoCMS project for testing.

Tech Stack

• Framework: React, TypeScript
• DatoCMS: datocms-plugin-sdk, datocms-react-ui
• Utilities:
  • json-2-csv (CSV generation)
  • jsontoxml (XML generation)
  • exceljs (Excel generation)
  • jszip (Asset zipping)

Export Contracts (Import-Oriented)

This section documents the concrete output contract of this plugin so you can build an importer with predictable behavior.

Record Export File Names

All record exports download with this filename pattern:

1
allDatocmsRecords<ISO_TIMESTAMP>.<extension>

Examples:

• allDatocmsRecords2026-02-10T18:12:33.271Z.json
• allDatocmsRecords2026-02-10T18:12:33.271Z.csv

Notes:

• JSON exports contain the full envelope described below (manifest, schema, projectConfiguration, referenceIndex, etc.).
• CSV, XML, and XLSX exports contain only the exported record data (no manifest/schema/reference index).

Asset ZIP File Names and Entry Names

Assets are split into one or more ZIP files using this naming template:

1
allAssets.part-<PPP>-of-<TTT>.<timestamp>.zip

• PPP and TTT are zero-padded to 3 digits (001, 012, etc.).
• timestamp is generated from new Date().toISOString().replace(/:/g, '-').
• Example: allAssets.part-003-of-012.2026-02-09T12-00-00.000Z.zip.

Each binary asset inside a ZIP uses:

1
u_<sourceUploadId>__<sanitizedOriginalFilename>

Sanitization rules:

• sourceUploadId:
  • trim
  • replace spaces with _
  • replace characters not matching [A-Za-z0-9_-] with -
  • collapse repeated -
  • fallback to unknown if empty
• originalFilename:
  • trim
  • replace spaces with _
  • replace characters not matching [A-Za-z0-9._-] with -
  • collapse repeated -
  • remove leading dots
  • fallback to file if empty

Example:

• Source: upload:123 + Hero Image (Final).png
• ZIP entry: u_upload-123__Hero_Image_-Final-.png

manifest.json Inside Each Asset ZIP

Every ZIP contains a manifest.json at the root with this structure:

1
type AssetZipManifest = {
2
  manifestVersion: "2.0.0";
3
  generatedAt: string; // ISO timestamp
4
  chunk: {
5
    index: number; // 1-based chunk index
6
    totalChunks: number;
7
    filename: string; // actual ZIP filename for this chunk
8
    assetCount: number;
9
    estimatedBytes: number; // conservative estimate used for chunking
10
  };
11
  conventions: {
12
    zipEntryName: "u_<sourceUploadId>__<sanitizedOriginalFilename>";
13
    zipFilename: "allAssets.part-{part}-of-{total}.{timestamp}.zip";
14
  };
15
  limits: {
16
    maxZipBytes: 157286400; // 150 * 1024 * 1024
17
    maxFilesPerZip: 100;
18
    sizeSafetyFactor: 1.2;
19
  };
20
  assets: AssetManifestEntry[];
21
};
22

23
type AssetManifestEntry = {
24
  sourceUploadId: string;
25
  zipEntryName: string;
26
  originalFilename: string;
27
  size: number | null;
28
  mimeType: string | null;
29
  width: number | null;
30
  height: number | null;
31
  checksum: string | null; // upload md5
32
  url: string | null;
33
  path: string | null;
34
  metadata: {
35
    // only included if present on the source upload:
36
    default_field_metadata?: unknown;
37
    field_metadata?: unknown;
38
    custom_data?: unknown;
39
    tags?: unknown;
40
    notes?: unknown;
41
    author?: unknown;
42
    copyright?: unknown;
43
    focal_point?: unknown;
44
    is_image?: unknown;
45
    blurhash?: unknown;
46
  };
47
};

JSON Record Envelope (.json record exports)

JSON record exports (bulk and single-record) use this envelope:

1
type RecordExportEnvelope = {
2
  manifest: {
3
    exportVersion: "2.1.0";
4
    pluginVersion: string;
5
    exportedAt: string; // ISO timestamp
6
    sourceProjectId: string | null;
7
    sourceEnvironment: string | null;
8
    defaultLocale: string | null;
9
    locales: string[];
10
    scope: "bulk" | "single-record";
11
    filtersUsed: {
12
      modelIDs?: string[];
13
      textQuery?: string;
14
    };
15
    configurationExport: {
16
      includedResources: (
17
        | "site"
18
        | "scheduledPublications"
19
        | "scheduledUnpublishings"
20
        | "fieldsets"
21
        | "menuItems"
22
        | "schemaMenuItems"
23
        | "modelFilters"
24
        | "plugins"
25
        | "workflows"
26
        | "roles"
27
        | "webhooks"
28
        | "buildTriggers"
29
      )[];
30
      warningCount: number;
31
    };
32
  };
33
  schema: {
34
    itemTypes: Record<string, unknown>[]; // raw itemTypes from CMA
35
    fields: Record<string, unknown>[]; // raw fields from CMA
36
    itemTypeIdToApiKey: Record<string, string>; // model id -> api_key
37
    fieldIdToApiKey: Record<string, string>; // field id -> api_key
38
    fieldsByItemType: Record<
39
      string,
40
      {
41
        fieldId: string;
42
        apiKey: string;
43
        fieldType: string;
44
        localized: boolean;
45
      }[]
46
    >;
47
  };
48
  projectConfiguration: {
49
    site: Record<string, unknown> | null; // full Site payload from CMA
50
    scheduledPublications: {
51
      itemId: string;
52
      itemTypeId: string | null;
53
      scheduledAt: string;
54
      currentVersion: string | null;
55
    }[];
56
    scheduledUnpublishings: {
57
      itemId: string;
58
      itemTypeId: string | null;
59
      scheduledAt: string;
60
      currentVersion: string | null;
61
    }[];
62
    fieldsets: Record<string, unknown>[];
63
    menuItems: Record<string, unknown>[];
64
    schemaMenuItems: Record<string, unknown>[];
65
    modelFilters: Record<string, unknown>[];
66
    plugins: Record<string, unknown>[];
67
    workflows: Record<string, unknown>[];
68
    roles: Record<string, unknown>[];
69
    webhooks: Record<string, unknown>[];
70
    buildTriggers: Record<string, unknown>[];
71
    warnings: {
72
      resource: string;
73
      message: string;
74
    }[];
75
  };
76
  records: Record<string, unknown>[]; // raw records from CMA iterator
77
  referenceIndex: {
78
    recordRefs: RecordReference[];
79
    uploadRefs: UploadReference[];
80
    structuredTextRefs: StructuredTextReference[];
81
    blockRefs: BlockReference[];
82
  };
83
  assetPackageInfo: {
84
    packageVersion: "2.0.0";
85
    zipNamingConvention: "allAssets.part-{part}-of-{total}.{timestamp}.zip";
86
    zipEntryNamingConvention:
87
      "u_<sourceUploadId>__<sanitizedOriginalFilename>";
88
    manifestFilename: "manifest.json";
89
    chunkingDefaults: {
90
      maxZipBytes: 157286400;
91
      maxFilesPerZip: 100;
92
      sizeSafetyFactor: 1.2;
93
    };
94
    lastAssetExportSnapshot: LastAssetExportSnapshot | null;
95
  };
96
};
97

98
type LastAssetExportSnapshot = {
99
  packageVersion: string;
100
  generatedAt: string;
101
  chunkFilenames: string[];
102
  totalChunks: number;
103
  totalAssets: number;
104
  maxZipBytes: number;
105
  maxFilesPerZip: number;
106
  sizeSafetyFactor: number;
107
};

Where references are:

1
type BaseRef = {
2
  recordSourceId: string;
3
  sourceBlockId: string | null;
4
  fieldApiKey: string;
5
  locale: string | null;
6
  jsonPath: string;
7
};
8

9
type RecordReference = BaseRef & {
10
  targetSourceId: string;
11
  kind: string;
12
};
13

14
type UploadReference = BaseRef & {
15
  targetSourceId: string;
16
  kind: string;
17
};
18

19
type StructuredTextReference = BaseRef & {
20
  targetSourceId: string;
21
  targetType: "record" | "block";
22
  kind: "link" | "block";
23
};
24

25
type BlockReference = BaseRef & {
26
  blockSourceId: string;
27
  blockModelId: string | null;
28
  parentBlockSourceId: string | null;
29
  kind: string;
30
  synthetic: boolean;
31
};

manifest Behavior Details

• manifest.exportVersion is currently fixed at 2.1.0.
• manifest.pluginVersion comes from:
  1. REACT_APP_PLUGIN_VERSION, else
  2. npm_package_version, else
  3. fallback "1.0.0".
• manifest.scope:
  • bulk for config-screen bulk exports
  • single-record for sidebar single-record export
• manifest.filtersUsed:
  • bulk export can include modelIDs and/or textQuery
  • single-record JSON export uses {}.
• Site fields (sourceProjectId, sourceEnvironment, defaultLocale, locales) are derived from projectConfiguration.site; if site fetch fails they fall back to null / [].
• manifest.configurationExport.includedResources lists all configuration collections shipped in projectConfiguration.
• manifest.configurationExport.warningCount is the number of non-fatal resource fetch failures collected in projectConfiguration.warnings.

Project Configuration Semantics

• projectConfiguration.site is the full raw site resource payload.
• scheduledPublications / scheduledUnpublishings are derived from exported records (meta.publication_scheduled_at / meta.unpublishing_scheduled_at) because CMA does not expose a global list endpoint for those resources.
• fieldsets are collected across all exported models/blocks.
• modelFilters comes from CMA item_type_filter resources.
• All arrays in projectConfiguration are present even when empty.
• projectConfiguration.warnings stores per-resource fetch failures without aborting the export.

Reference Index Semantics

• jsonPath always points to the location in records where the relationship was found.
• Path root starts at $.records[index].
• Localized fields include locale in both:
  • jsonPath (for example $.records[0].content.en.document...)
  • locale property ("en", "pt", etc.).
• sourceBlockId is null for top-level record fields and set for relationships found inside blocks.
• Deduplication is applied; each unique (context + target + kind) is emitted once.

kind values currently emitted by this version:

• recordRefs.kind: link, links, structured_text_itemLink, structured_text_inlineItem, structured_text_links_array, unknown_item
• uploadRefs.kind: file, gallery, unknown_upload
• blockRefs.kind: modular_content, single_block, nested_block, structured_text_block, structured_text_blocks_array

When a block-like object has no id, the exporter creates a synthetic block ID:

1
synthetic::<recordSourceId>::<jsonPath>

This appears in blockRefs.blockSourceId with synthetic: true.

Import Guidance (Recommended Order)

If you are writing an importer, this order is reliable for the current contract:

1. Read schema maps (itemTypeIdToApiKey, fieldIdToApiKey, fieldsByItemType) and projectConfiguration.
2. Recreate project-level configuration resources as needed (site, menu/schema menu items, workflows, roles, webhooks, build triggers, etc.).
3. Import assets from ZIPs and build sourceUploadId -> targetUploadId mapping from each ZIP manifest.json.
4. Create records first (without resolving all links yet), preserving a sourceRecordId -> targetRecordId map.
5. Reconcile links/uploads/blocks using referenceIndex.
6. Apply structured text links and block references in a final pass using structuredTextRefs and blockRefs.

License

This project is licensed under the MIT License.