> For the complete documentation index, see [llms.txt](https://docs.boldminded.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.boldminded.com/bloqs/docs/features/import-and-export.md).

# Import & Export

Bloqs 5.5 lets you export selected bloq definitions to a JSON file and re-import them into another ExpressionEngine site. Use it to move bloqs from local to production, between staging sites, or to share a set of bloqs with another project. Only the definitions are exported (the bloq types, their fields, settings, nesting rules, and component structure). Entry content is never exported; it stays in the entries on each site.

{% hint style="warning" %}
BoldMinded is not responsible for data loss when using this feature. 

**Backup your database before running imports.**
{% endhint %}

### Exporting

On the **Bloqs** listing screen, each row has a checkbox. Select one or more definitions, choose **Export** from the bulk-action bar that appears, and submit. Your browser downloads a JSON file named `bloqs-definitions-N.json`.

The export is self-contained and human-readable. Because the receiving site won't share the same database IDs, every cross-reference is rewritten into a portable form:

* **Bloq groups** are exported by name.
* **Nesting rules** ("can be a child of...") are exported as shortnames.
* **Component child bloqs** are referenced by shortname.

#### Example export

```json
{
  "bloqs_export_version": 1,
  "source": {
    "bloqs_version": "5.5.0"
  },
  "block_definitions": [
    {
      "shortname": "hero",
      "name": "Hero",
      "instructions": "A full-width hero banner.",
      "group": "Layout",
      "deprecated": 0,
      "deprecated_note": "",
      "preview_image": "",
      "preview_icon": "image",
      "is_component": 0,
      "is_editable": 0,
      "settings": {
        "nesting": {
          "root": "any",
          "child_of": ["section"],
          "no_children": "y"
        }
      },
      "atom_definitions": [
        {
          "shortname": "headline",
          "name": "Headline",
          "instructions": "",
          "order": 0,
          "type": "text",
          "settings": { "field_fmt": "none", "col_required": "y" }
        },
        {
          "shortname": "related",
          "name": "Related Entry",
          "instructions": "",
          "order": 1,
          "type": "relationship",
          "settings": { "channels": ["3"], "authors": [], "limit": "1" }
        }
      ]
    }
  ]
}
```

A **component** bloq also carries a `component_children` array listing the child bloqs by shortname along with their tree position (`order`, `depth`, `parent_id`, `lft`, `rgt`, `cloneable`).

The `bloqs_export_version` field is the format version. A site running an older version of Bloqs refuses a file whose version is newer than it understands.

### Importing

Use the **Import** screen to upload an exported file. You upload the file and choose options, then see a preview of exactly what will happen. Nothing is written until you confirm.

#### The import options

**Definition File** (required): the JSON file you exported.

**Preserve Site-Specific Settings** (off by default): when off, field settings that reference site-specific IDs are reset to safe defaults. Turn it on only when the target site shares the same channel, upload-directory, and field IDs as the source, such as a local-to-production sync of the same site. See "The site-specific settings rule" below.

**Update Existing Definitions** (off by default): when off, a matching shortname is imported as a renamed copy. When on, matching bloqs are updated in place. See "Adding vs. updating" below.

**Remove Atoms Not In File** (off by default, only applies when "Update Existing" is on): deletes fields on the target that aren't in the file. This is destructive, since deleting a field also deletes its content in every entry that uses it. The preview shows which fields would be deleted and how many entries would lose content.

#### The preview

Before committing, you get a dry-run summary:

* **Will be created**: definitions that don't exist on the target.
* **Will be updated**: existing definitions updated in place (only when "Update Existing" is on).
* **Renamed to avoid collisions**: definitions whose shortname already exists and will get a numeric suffix.
* **Fields needing reconfiguration**: fields whose site-specific settings will be reset.
* **Atoms to be deleted**: fields that will be removed, each with the count of affected entries.

### The rules: adding, updating, deleting

#### Adding (the default)

With "Update Existing" off, every definition is created new. If a shortname already exists on the target (whether from another bloq or a native channel field), the imported copy gets a unique suffix: `hero` becomes `hero_2`, then `hero_3`. An import can never overwrite existing data this way; the worst case is a renamed duplicate. References within the import (nesting, component children) are rewired to point at the renamed copies.

#### Updating (opt-in)

With "Update Existing" on, a definition whose shortname matches one on the target is updated in place. This updates the bloq and its fields:

* The bloq's own properties (name, instructions, group, deprecation, preview image/icon, component flags, nesting settings) are overwritten from the file.
* Each field is matched by shortname within that bloq:
  * A field on both is updated in place, keeping its existing database ID. Since entry content is tied to that ID, no content is lost.
  * A field in the file but not on the target is created.
  * A field on the target but not in the file is left untouched by default.

#### Deleting (explicit, destructive)

An import never deletes anything unless you ask. The only deletion path is **"Remove Atoms Not In File"**, available only in update mode. When enabled, fields on the target but absent from the file are deleted, and deleting a field cascades to its content in every entry. The preview lists each field with its entry-usage count. Whole definitions are never deleted by an import; to remove a bloq, use the delete action on the Bloqs listing (which is blocked while the bloq is in use).

### The site-specific settings rule

Some field types store references identified by site-local IDs: relationship fields point at channels, categories, statuses, and authors; file and Assets fields point at upload directories. These IDs are meaningless on a different site.

Unless "Preserve Site-Specific Settings" is on, the importer resets these references to safe empty defaults for the affected types (relationship, file, file\_grid, assets). The field is imported intact and usable, just unconfigured for those references, which you reconnect on the target. The preview lists every affected field. The rest of a field's settings (label, limits, required, formatting) are always preserved.

Turn this option on only when the target's IDs match the source's, typically a local-to-production sync of the same site.

### The `renamed_from` nuance

The importer matches definitions and fields by shortname. If you rename `headline` to `title` in the source and import with "Update Existing" on, the importer can't tell `title` is the old `headline`. It sees `headline` as gone and `title` as new, so it creates a new empty `title` and leaves the old field alone.

To handle a rename, add a `renamed_from` property by hand to that entry in the JSON before importing. It tells the importer: if you can't find my current shortname, look for this old one and update that record in place.

```json
{
  "shortname": "title",
  "name": "Title",
  "type": "text",
  "renamed_from": "headline",
  "settings": { }
}
```

With this and "Update Existing" on, the importer finds the existing `headline` field, updates it in place (keeping its ID and all entry content), and changes its shortname to `title`. The same works at the bloq level: `"renamed_from": "hero"` with `"shortname": "hero_banner"` updates the existing `hero` bloq and renames it.

Notes on `renamed_from`:

* It's matched only as a fallback. The current shortname is tried first, so it's harmless to leave in a file you re-import.
* It's supplied by hand. Bloqs doesn't auto-detect renames or write `renamed_from` into exports, because the database keeps no rename history.
* It works safely with "Remove Atoms Not In File": a field matched via `renamed_from` has its old shortname treated as accounted for, so the remove step won't delete it.

Within a single site you never need `renamed_from`. Just rename the field in the control panel; content is tied to the field's ID, so nothing is lost. `renamed_from` exists only for cross-site imports, where the two sites share no ID and the shortname is the only stable key.