> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alumio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem: Write files

> Writes data to a file on a filesystem.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Writes content to a file on a filesystem. Use this to save the data flowing through a route as a file, for example exporting an order as a JSON file, dropping a generated CSV onto an FTP server, or saving a downloaded document. You decide both where the file is written and what goes into it, and each can come either from a value already in the data or from a custom value you type in. When the file path is taken from the data, the final path that was actually used (which can differ if a rename strategy kicked in) is written back into the data at that same location, so later steps can see where the file ended up.

This documentation describes: [Schema](/schemas/transformer/filesystem-write-file)

## Fields

<FormField property="filesystem" label="Filesystem connection" required diType="filesystem">
  The filesystem connection the file is written to.
</FormField>

<FormField property="ensureDestination" label="When the file exists" diType="filesystem-ensure-destination">
  What to do when a file with the same path already exists. Leave it empty to overwrite the existing file (the default), which replaces its previous content. Choose a rename strategy instead to keep the existing file and write to a new, non-conflicting name, for example by adding an increasing number.
</FormField>

<FormField property="configuration" label="File path and contents" required diType="filesystem-write-configuration">
  Defines the file itself, in two parts. The path decides where the file is written: point at a value already in the data (for example `images.0.path`) or type a custom path such as `exports/&{order.id}.json`, using [placeholders](/references/placeholders) to build it from the data. The contents decide what goes into the file: again, take it from a value in the data or type custom content with placeholder support. A mapper can be applied to each part to reshape the path or format the contents, for example into JSON or XML.
</FormField>

## Sample data

This step writes a file rather than transforming the data, so there is no before/after to show. The configuration below writes each order to its own JSON file under an `exports` folder, taking the file name from the order id and overwriting any existing file with the same name.

| Field                 | Value                                        |
| --------------------- | -------------------------------------------- |
| Filesystem connection | The connection files are exported to         |
| When the file exists  | Overwrite (left empty)                       |
| Path                  | Custom path `exports/order-&{order.id}.json` |
| Contents              | Custom content built from the data           |

```json Configuration theme={null}
{
  "prototype": "filesystem-write-file",
  "parameters": {
    "filesystem": "export-files",
    "configuration": {
      "path": {
        "source": "custom",
        "custom": "exports/order-&{order.id}.json"
      },
      "contents": {
        "source": "custom",
        "custom": "{\"order\":\"&{order.id}\",\"total\":\"&{order.total}\"}"
      }
    }
  }
}
```