Assets

Files on local volumes are copied into the bundle. Files on remote filesystems are referenced by URL and not downloaded — so a site with tens of gigabytes of cloud media still produces a bundle you can hand someone.

Where files land

assets/<volumeHandle>/<folderPath>/<filename>

assets/images/hero.jpg
assets/images/team/portrait.jpg
assets/documents/2026/report.pdf

The volume handle and folder path are preserved, so the layout inside the ZIP mirrors the layout in Craft. Files are copied byte for byte — no re-encoding, no transforms — and deduplicated, so two entries pointing at the same image produce one file.

Bundled or referenced

Every asset reference says which it is:

{
  "uid": "…", "id": 14, "type": "asset", "title": "hero.jpg",
  "filename": "hero.jpg", "kind": "image", "mimeType": "image/jpeg",
  "size": 184213, "width": 2000, "height": 1333,
  "alt": "A hero image", "volume": "images",
  "url": "https://example.com/uploads/hero.jpg",

  "bundled": true,
  "path": "assets/images/hero.jpg"
}

• bundled: true — the bytes are in the ZIP at path. This is what happens for volumes on a local filesystem.
• bundled: false — the file lives on a remote filesystem (S3, Spaces, GCS…) and only the url is given, deliberately, to keep the bundle small. Fetch it from url at import time.

An asset record’s file key holds the same metadata a reference does, so a record and a reference to it describe the file identically. One code path in the importer covers both.

Downloading remote files anyway

If you do want the bytes — you’re decommissioning the bucket along with the site, say — turn on Download remote asset files on the export screen, or set downloadRemoteAssets in the settings to make it the default. Remote files then arrive with bundled: true like any other, and the bundle gets as large as the media library.

The size limit

Files larger than maxAssetFileSize (256 MB by default) are referenced rather than copied, however local they are, and each one is noted in the manifest’s warnings. Set it to 0 to disable the limit entirely.

That limit exists because a single 4 GB video will otherwise silently turn a portable bundle into something nobody can move. If you want it in the ZIP, raise the setting on purpose.

Metadata-only exports

Turn Include asset files off and Archive exports asset records and URLs without copying anything. This is the right choice when the files are staying where they are — a CDN you’re keeping, or a bucket the new platform will read directly — and it makes bundles dramatically smaller.

Assets in their own right

Ticking Assets on the export screen collects every asset in the selected volumes, not just the ones something links to. Unreferenced files travel too, and dedupe against the ones entries already pulled in, so nothing is copied twice.

Use the Volumes filter to narrow it — a bundle that needs the document library but not eight years of blog imagery is a much easier thing to move.

What’s counted

The manifest’s assets block is the record of what happened:

"assets": {
  "included": 42,       copied into the ZIP
  "referenced": 7,      left where they are, URL only
  "skipped": 1,         unreadable, or over the size limit — see warnings
  "bytes": 18452113,
  "files": ["assets/images/hero.jpg", "…"]
}

Every file that made it in is listed by path, so you can verify a bundle against its own manifest without unzipping it twice.