plist

library1.0.0jsnpmunverified

The `plist` library provides robust facilities for parsing and building Apple Property List (Plist) files in both Node.js and browser environments. Plists are XML-based or binary structured data files commonly used in macOS and iOS applications, akin to JSON for configuration and data storage. The current stable version is 3.1.0, and it maintains an active development status with releases primarily driven by bug fixes, dependency updates, or feature enhancements. Key differentiators include its cross-platform compatibility, support for both XML and binary plist formats (implied by typical plist library functionality, though README focuses on XML), and its straightforward API for converting between JavaScript objects and plist XML strings. This package is an essential tool for developers working with Apple-specific file formats outside of the Apple ecosystem, providing programmatic access to data found in `.plist` files, such as `Info.plist` or iTunes configuration files.

serialization

npm install plist

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PLIST

plist

serializationjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plist (CommonJS)

✓ const plist = require('plist');

This is the primary way to import and use the library in Node.js CommonJS modules, as demonstrated in the package's documentation.

plist (ESM Default)

✓ import plist from 'plist';

✗ import { plist } from 'plist';

While the README primarily shows CommonJS, modern Node.js and browser environments typically use ESM. The package provides a default export for the `plist` object containing `parse` and `build` methods.

parse and build (as named exports)

✓ import plist from 'plist'; const parsed = plist.parse(xml); const built = plist.build(obj);

✗ import { parse, build } from 'plist';

The `parse` and `build` functions are methods on the default `plist` object, not named exports from the top-level module. Attempting to destructure them directly from the module import will result in `undefined` values.

Demonstrates parsing a plist XML string into a JavaScript object and then building a plist XML string from a JavaScript object using the library's main `parse` and `build` functions.

import plist from 'plist'; const xmlString = `<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.company.app</string> <key>bundle-version</key> <string>0.1.1</string> <key>kind</key> <string>software</string> <key>title</key> <string>AppName</string> </dict> </plist>`; // Parse the XML string into a JavaScript object const parsedObject = plist.parse(xmlString); console.log('Parsed Object:', parsedObject); // Build a new plist XML string from a JavaScript object const dataToBuild = [ 'metadata', { 'bundle-identifier': 'com.company.newapp', 'bundle-version': '1.0.0', 'kind': 'software', 'title': 'New App Name' } ]; const builtXml = plist.build(dataToBuild); console.log('Built XML:\n', builtXml);

Debug

Known issues

breakingVersion 3.x introduced changes that may affect older Node.js versions or browser environments. Ensure your runtime supports ES Modules if you are using `import` syntax, as older versions of Node.js (pre-12.x) may require `--experimental-modules` or be incompatible.

fix

For Node.js, ensure your environment is Node.js 12.x or higher for native ESM support, or continue using `require()` for CommonJS modules. For browsers, ensure proper bundler configuration if using ESM imports.

affects: >=3.0.0

gotchaThe `plist.parse()` function expects a well-formed XML string representing a plist. Providing malformed XML, non-plist XML, or non-string input can lead to parsing errors or unexpected output.

fix

Always validate the input string before passing it to `plist.parse()`. Ensure it's a string and adheres to the plist DTD. Wrap calls in a `try...catch` block to handle potential parsing exceptions gracefully.

affects: >=1.0.0

gotchaThe `plist.build()` function expects a JavaScript object or array that can be directly mapped to plist data types. Providing complex or non-standard JavaScript objects may result in malformed plist XML or errors.

fix

Structure your JavaScript object to closely mirror the expected plist structure (e.g., plain objects for dictionaries, arrays for arrays, primitive types for strings/numbers/booleans). Avoid circular references or non-serializable objects.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: plist.parse is not a function

Attempting to call `parse` on an `undefined` or incorrectly imported `plist` object, often due to a mixed CommonJS/ESM environment or incorrect `require`/`import` syntax.

fix

Verify that `plist` is correctly imported. If using CommonJS, `const plist = require('plist');` is correct. If using ESM, `import plist from 'plist';` should be used, as `parse` is a method of the default export, not a named export itself.

Error: Unknown plist type 'undefined'

This error typically occurs within the `plist.build()` function when it encounters a JavaScript value it doesn't know how to serialize into a plist XML tag.

fix

Review the JavaScript object being passed to `plist.build()`. Ensure all values are primitive types (string, number, boolean), arrays, or plain objects (dictionaries). Avoid `null`, `undefined`, functions, or complex class instances that `plist` cannot automatically convert.

SyntaxError: Unexpected token '<'

This error might occur when a bundler or runtime tries to interpret plist XML content as JavaScript code, likely due to loading a `.plist` file directly without processing it through the `plist.parse` function, or attempting to `require()` a `.plist` file directly.

fix

Ensure that plist XML content is read as a string (e.g., using `fs.readFileSync` in Node.js) and then explicitly passed to `plist.parse()`. Do not attempt to `import` or `require` a `.plist` file directly.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/TooTallNate/plist.js ↗

packagehttps://www.npmjs.com/package/plist ↗

homepagehttps://www.npmjs.com/package/plist ↗