plist.js

When parsing or building, the following mapping between Plist types and JavaScript types is used:

You can quickly parse any supported plist format (XML, binary, or OpenStep) using parse() and build an XML plist from a JavaScript object using build().

import { parse, build } from 'plist';

// Parse any plist format (auto-detected)
const obj = parse('<plist version="1.0"><string>Hello!</string></plist>');
console.log(obj); // "Hello!"

// Build an XML plist from a JS object
const xml = build({ name: 'My App', version: 42 });
console.log(xml);

Install the plist package using npm to use it in Node.js or browser-based projects.

npm install plist

In bundled applications (Vite, webpack, etc.), you can import plist normally. The library uses conditional exports to automatically select a browser-optimized build that uses native DOMParser and avoids heavy dependencies like @xmldom/xmldom or xmlbuilder.

import { parse, build } from 'plist';

When using build(), JavaScript types are mapped to specific XML plist tags as follows:

• String: <string>
• Number (Integer): <integer> (if n % 1 === 0)
• Number (Float): <real> (if n % 1 !== 0)
• BigInt: <integer>
• Boolean: <true/> or <false/>
• Date: <date> (formatted as an ISO 8601 string without milliseconds, e.g., YYYY-MM-DDTHH:mm:ssZ)
• Array: <array>
• Object/Dictionary: <dict> containing <key> elements
• Binary Data (ArrayBuffer, Uint8Array, Buffer, or other ArrayBufferView): <data> (encoded as a Base64 string)

Convert JavaScript objects into plist formats.

XML Output

Use build(obj, opts?) to generate an XML string. By default, it uses pretty-printing.

Binary Output

Use buildBinary(obj) to generate a Uint8Array containing a binary plist (bplist00).

import { writeFileSync } from 'node:fs';
import { build, buildBinary } from 'plist';

// Build XML
const xml = build({
  CFBundleName: 'My App',
  CFBundleVersion: '1.0',
  LSRequiresIPhoneOS: true,
  UISupportedInterfaceOrientations: [
    'UIInterfaceOrientationPortrait',
    'UIInterfaceOrientationLandscapeLeft',
  ],
});

// Build Binary
const data = buildBinary({
  CFBundleName: 'My App',
  CFBundleVersion: '1.0',
});
writeFileSync('Info.plist', data);

The build function accepts an optional BuildOptions object to control the formatting of the generated XML string.

import { build } from 'plist';

const obj = { name: 'example' };

// Example with custom indentation and no pretty-printing
const xml = build(obj, {
  pretty: false,
  indent: '  ',
  newline: '\n'
});

The build function accepts an optional BuildOptions object to control the formatting of the generated XML string.

Options

• pretty (boolean, optional): Determines if the output is indented. Defaults to true if not provided or if set to true. Set to false for a minified output.
• indent (string, optional): The string used for indentation when pretty is enabled. Defaults to ' ' (two spaces).
• newline (string, optional): The string used for line separators when pretty is enabled. Defaults to \n.
• [key: string]: unknown: Allows for additional properties.

import { build } from 'plist';

const obj = { name: 'example' };

// Minified output
const minified = build(obj, { pretty: false });

// Custom indentation and newlines
const custom = build(obj, {
  pretty: true,
  indent: '\t',
  newline: '\r\n'
});

The following methods are available for parsing and building plists.

### `parse(input)`
Parse a plist. Format is auto-detected.
- **input**: `string | Uint8Array | ArrayBuffer`
- **returns**: `PlistValue`

### `parseBinary(data)`
Parse a binary plist (bplist00).
- **data**: `Uint8Array`
- **returns**: `PlistValue`

### `parseOpenStep(input)`
Parse an OpenStep/ASCII plist.
- **input**: `string`
- **returns**: `PlistValue`

### `build(obj, opts?)`
Build an XML plist string.
- **obj**: `PlistValue`
- **opts.pretty**: `boolean` (default: `true`)
- **opts.indent**: `string` (default: `"  "`)
- **opts.newline**: `string` (default: `"\n"`)
- **returns**: `string`

### `buildBinary(obj)`
Build a binary plist (bplist00).
- **obj**: `PlistValue`
- **returns**: `Uint8Array`

The parse function is the primary entry point for decoding various plist formats into a JavaScript object. It automatically detects the format based on the input type and content:

• XML Plists: Standard XML strings or buffers starting with <plist.
• Binary Plists: ArrayBuffer or Uint8Array inputs, or strings starting with the bplist prefix.
• OpenStep/ASCII Plists: Strings starting with { or ( that do not contain XML declarations.

Returns a PlistValue representing the decoded data.

import { parse } from 'plist';

// Parsing an XML string
const xml = `<plist><dict><key>example</key><string>value</string></dict></plist>`;
const data = parse(xml);

// Parsing a binary plist (Uint8Array)
const binaryData = new Uint8Array([...]);
const dataFromBinary = parse(binaryData);

Use build() to convert a JavaScript object into an XML plist string.

import { build } from 'plist';

const obj = { Hello: 'World' };
const xml = build(obj);
// Output: '<plist version="1.0"><dict><key>Hello</key><string>World</string></dict></plist>'