How it works
DocumentWriteConfiguration carries the information SwiftUI hands to a document type at the moment it serializes itself to disk. When the document-based scaffolding needs to save, it calls your document's write method and passes one of these values, telling you the content type being written and—on an overwrite—the file that already exists on disk. Reach for it inside a FileDocument or ReferenceFileDocument so you can produce the correct bytes for the format being saved and, when present, reuse or update the existing file rather than blindly replacing it. In SwiftUI it is surfaced through the WriteConfiguration typealias, the parameter type your fileWrapper(configuration:) method declares.
Receive it in fileWrapper(configuration:)
A FileDocument serializes by implementing the writing method that returns a FileWrapper, and the framework supplies a write configuration as its single argument. In the example,
func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapperis where the document turns its in-memory state into bytes, returning aFileWrapper(regularFileWithContents: data)built from the document'stext.Read the existing file with existingFile
On a save that overwrites a document already on disk, the configuration's existingFile holds the current FileWrapper, letting you preserve or amend it instead of writing a wholly new one. The example unwraps it with
if let existing = configuration.existingFileand adjustsexisting.preferredFilename = "note.txt"; on a first save existingFile is absent, so this branch is skipped.Honor the requested content type
The configuration also reports which of the document's content types is being written, so a document that declares several formats can branch on the destination type. The format set is declared up front—here
static var readableContentTypes: [UTType] { [.plainText] }—and the write method's job is to emit data matching the type the configuration names, in this case plain-text bytes viaData(text.utf8).Pair it with ReadConfiguration
DocumentWriteConfiguration is the save-side counterpart to the read configuration used when loading. The same type implements
init(configuration: ReadConfiguration) throwsto decode a document, while the write configuration governs the reverse trip; together they bracket the full document lifecycle that FileDocument conformance requires.
if let existing branch, change existing.preferredFilename = "note.txt" to a different name and observe that the overwritten file is renamed only when configuration.existingFile is non-nil—that is, on a re-save rather than the initial write.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct DocumentWriteConfigurationDemo: View {
struct TextFile: FileDocument {
static var readableContentTypes: [UTType] { [.plainText] }
var text: String
init(text: String = "Hello") { self.text = text }
init(configuration: ReadConfiguration) throws {
self.text = ""
}
func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
let data = Data(text.utf8)
if let existing = configuration.existingFile {
existing.preferredFilename = "note.txt"
}
return FileWrapper(regularFileWithContents: data)
}
}
var body: some View {
VStack(spacing: 12) {
Image(systemName: "doc.text")
.font(.largeTitle)
Text("FileDocument")
.font(.headline)
Text("fileWrapper(configuration:) receives a WriteConfiguration with the existing file and content type.")
.font(.caption)
.multilineTextAlignment(.center)
.foregroundStyle(.secondary)
}
.padding()
}
}