How to import a CSV file into EmDash
Prepare a collection, preview a CSV import and update entries with the free Sneaps Import/Export plugin.
Start with the collection, not the spreadsheet
You can import CSV content into EmDash with @sneaps/import-export. Install the native plugin, choose a collection, upload a file and check the preview before saving. An import transfers entries into an existing content structure; it does not build your page templates.
Before preparing hundreds of rows, decide where the content belongs. A collection for articles might need a title, slug, excerpt and body. Check which fields are required and which field names the collection actually uses. The examples below use illustrative names: your collection schema is the reference.
Install the native Import/Export plugin
Add the package to your project, then register importExport() in the existing EmDash configuration in astro.config.mjs. Preserve your other integrations and plugins. Rebuild and deploy the site after changing the configuration.
An Import/Export entry then appears in the administration sidebar. This workflow is for administrators with the necessary import and content permissions. It is an npm installation, rather than an installation from the sandboxed plugin registry.
pnpm add @sneaps/import-export
// astro.config.mjs
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { importExport } from "@sneaps/import-export";
export default defineConfig({
integrations: [
emdash({
plugins: [importExport()],
// Preserve your other EmDash settings and plugins.
}),
],
});Build a small CSV that matches your fields
Use a header row with unique names and UTF-8 encoding. Name the columns after collection fields; use slug or id when you need to identify existing entries. Exporting an empty template from the plugin is a good starting point because it gives you the collection’s columns.
Start with two or three representative rows. Include an accented title, punctuation and a rich-text value if your real dataset contains them. A comma inside a value needs CSV quoting. Keep slugs consistent between repeated imports so an editorial correction does not accidentally become a new entry.
title,slug,excerpt
"A practical guide",practical-guide,"An introduction, with a comma"
"Second article",second-article,"Another example"Read the preview before starting
Open the Import tab, select your collection and upload the file. Review the detected format, field mappings, create/update counts and warnings. Nothing has been saved at the preview stage. Choose the rich-text format for the relevant columns and check that the first rows look right.
This release does not import image, file, reference, repeater or blocks fields. Plan those separately instead of expecting a media URL to become an uploaded image. If a required field is missing, fix the source file or collection mapping before proceeding.
Choose how entries should be saved
For a first test, saving as drafts makes review easier. Decide whether the import should create and update entries or only create. The plugin matches an entry by id first, otherwise by slug, taking locale into account when supplied.
An empty CSV cell means no value; an update does not use it to blank an existing field. If your objective is to remove content from a field, review it in EmDash rather than assuming an empty spreadsheet cell will erase it. Export existing content before a bulk update so you can compare the result with the previous state.
Run the import and verify the result
Keep the browser tab open while the import runs. Review failed rows and download their error report. Check entry counts, a few saved records, rich-text rendering and the actual pages before publishing. A successful save is only one part of a successful content transfer.
The documented limits are 8 MiB and 5,000 rows per import. Split larger datasets into clearly named batches and test the first one before continuing. If a slug belongs to an entry in the trash, resolve that conflict before retrying. For JSON preservation and reusable exports, read the companion export guide.
CSV / JSON export guide