simple-plist utility

1.3.1 · active · verified Sun Apr 19

simple-plist is a wrapper utility for interacting with Apple Property List (plist) data, supporting both binary and XML formats. The current stable version is 1.3.1. While its release cadence is not rapid, the package demonstrates active maintenance, as evidenced by the recent v1.3.0 rewrite into TypeScript to provide strong typing. It offers a straightforward API for reading and writing plist files synchronously and asynchronously, as well as in-memory parsing and stringification. This package serves as a convenient abstraction over lower-level plist parsing libraries, making it easier to manage `.plist` files commonly found in macOS and iOS environments, without requiring direct interaction with the underlying `plist` or `bplist` packages.

Common errors

```
TypeError: plist.readFileSync is not a function
```
cause Attempting to access a function (e.g., `readFileSync`) directly from a default import or incorrectly requiring the module in an ESM context.

fix Ensure you are using `import * as plist from 'simple-plist';` for ESM, or `const plist = require('simple-plist');` for CommonJS. Alternatively, use named imports like `import { readFileSync } from 'simple-plist';`.
```
Error: ENOENT: no such file or directory, open '/path/to/non-existent.plist'
```
cause The specified plist file does not exist at the provided path, or the path is incorrect.

fix Verify the file path is correct and that the file actually exists. Use `path.join()` for robust path construction across different operating systems.
```
Error: unable to parse plist
```
cause The input string or file content is not a valid XML or binary plist format, or is malformed.

fix Inspect the plist content for structural correctness. Ensure it conforms to Apple's Property List DTD for XML plists or the binary plist specification. Tools like `plutil` (on macOS) can validate plist files.

Warnings

breaking Support for Node.js 6 was dropped in version 1.1.0. Users on older Node.js versions must upgrade their Node.js runtime or remain on an older `simple-plist` version.
Fix: Upgrade your Node.js runtime to version 8 or higher (or a currently supported LTS version).
gotcha The `v1.3.0` release involved a complete rewrite of the codebase into TypeScript. While declared to have 'minimal risk' for existing JavaScript users, subtle behavioral changes or type inference issues might arise for projects not using TypeScript or those relying on implicit behaviors.
Fix: Thoroughly test your application after upgrading. If using JavaScript, be mindful of stricter behavior that might stem from the underlying TypeScript types. Consider adopting TypeScript for better type safety.
gotcha When using `simple-plist` in an asynchronous context, be aware that the asynchronous functions (e.g., `readFile`, `writeFile`) use Node.js-style callbacks. For promise-based workflows, you can wrap these functions using `util.promisify`.
Fix: Use `const { promisify } = require('util'); const readFileAsync = promisify(plist.readFile);` to convert callback-based functions to return Promises for easier async/await usage.

Install

npm install simple-plist npm
yarn add simple-plist yarn
pnpm add simple-plist pnpm

Imports

* as plist
wrong:
```
import plist from 'simple-plist'; // Incorrect default import
```
correct:
```
import * as plist from 'simple-plist';
```
This is the recommended way to import all functions in ESM contexts, especially when using TypeScript, allowing access via `plist.readFile`, `plist.writeFileSync`, etc.
{ readFileSync, writeFileSync }
wrong:
```
const { readFileSync, writeFileSync } = require('simple-plist'); // CommonJS, not ESM
```
correct:
```
import { readFileSync, writeFileSync } from 'simple-plist';
```
For specific synchronous file operations, named imports are efficient. Other common named exports include `readFile`, `writeFile`, `parse`, `stringify`, `readBinaryFileSync`, `writeBinaryFileSync`, etc.
require('simple-plist')
wrong:
```
import plist from 'simple-plist'; // Incompatible with CommonJS modules
```
correct:
```
const plist = require('simple-plist');
```
This is the standard CommonJS import pattern. Access functions directly from the `plist` object, e.g., `plist.readFileSync`. This pattern is primarily for Node.js environments not configured for ESM.
parse
wrong:
```
import { parse: parsePlist } from 'simple-plist'; // Unnecessary alias if not conflicting
```
correct:
```
import { parse } from 'simple-plist';
```
Used for parsing plist content directly from a string or buffer into a JavaScript object. This function also supports TypeScript generics for type-safe parsing.

Quickstart

Demonstrates how to write a JavaScript object to a plist file and then read it back, using synchronous file operations and TypeScript types.

import { writeFileSync, readFileSync } from 'simple-plist';
import * as path from 'path';
import * as fs from 'fs';

const tempFilePath = path.join(process.cwd(), 'temp.plist');

type AppConfig = {
  appName: string;
  version: string;
  debugMode: boolean;
  settings: { theme: string; language: string };
};

const config: AppConfig = {
  appName: 'MyAwesomeApp',
  version: '1.0.0',
  debugMode: true,
  settings: { theme: 'dark', language: 'en-US' },
};

try {
  // Write the object to an XML plist file
  writeFileSync(tempFilePath, config);
  console.log('Plist file written successfully:', tempFilePath);

  // Read the plist file back into an object
  const readConfig = readFileSync(tempFilePath) as AppConfig;
  console.log('Plist file read successfully:', readConfig);
  console.log('App Name:', readConfig.appName);
  console.log('Version:', readConfig.version);
} catch (error) {
  console.error('An error occurred:', error);
} finally {
  // Clean up the temporary file
  if (fs.existsSync(tempFilePath)) {
    fs.unlinkSync(tempFilePath);
    console.log('Temporary plist file cleaned up.');
  }
}

view raw JSON →