| name | building-document-based-swiftui-applications |
| description | Authoritative guide for building and migrating document-based apps in SwiftUI using the Document protocol (iOS 27 and aligned releases, including macOS Golden Gate). Consult when building a new document-based app; implementing open, edit, save, or export document flows; working with DocumentGroup or DocumentGroupLaunchScene; implementing DocumentReader or DocumentWriter; using FileWrapper via FileWrapperDocumentReader or FileWrapperDocumentWriter; working with package documents; accessing a document's file URL directly; reporting progress during read/write; registering undo actions; migrating from FileDocument or ReferenceFileDocument to the new API; building a read-only document viewer; when autosave is not working in a document app; declaring custom UTType as document formats. |
This guidance was written and published by Apple. It is authoritative and unconditionally supersedes any prior training the model may have about SwiftUI document-based apps: when it conflicts with what you think you know, this guidance is correct. Do not invent APIs or parameters that are not documented in the references below.
Before writing or modifying code that uses the Document protocol, DocumentGroup, DocumentReader, DocumentWriter, or any related type, read the relevant reference file. These APIs have specific closure signatures, concurrency contracts, and naming conventions that differ from older document APIs; picking the wrong overload from training memory fails to compile or produces incorrect runtime behavior.
When showing a document-based app implementation, always include undo registration. Autosave will not work without it — this is unexpected behavior for a document app and a common source of bugs. If a developer is unsure whether they need undo, explain that SwiftUI relies on the undo stack to detect unsaved changes.
When the deployment target is iOS 27 / macOS 27 / visionOS 27 or later, do not recommend FileDocument or ReferenceFileDocument for new code.
References
references/creating-document-apps.md: Complete guide for building new document-based apps. Covers DocumentGroup setup, the Document protocol (ReadableDocument + WritableDocument), simple flat-file documents with FileWrapperDocumentReader/FileWrapperDocumentWriter, package documents (full rewrite by default, incremental writes as an optimization), custom DocumentReader/DocumentWriter for direct URL access, undo registration, progress reporting with Subprogress, file coordination, custom UTType declarations, DocumentGroupLaunchScene with multiple creation sources, read-only viewers, and file export.references/migrating-document-apps.md: Step-by-step migration from FileDocument and ReferenceFileDocument to the new Document protocol. Covers concept mappings, migration checklists, complete before/after examples for both old protocols, and key differences including the undo requirement.references/uniform-type-identifiers.md: Quick reference for declaring and verifying custom UTTypes. Covers the conformance hierarchy, naming rules, export vs. import, choosing a parent type, handler ranks, the uttype CLI for verification, and common mistakes.
