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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
* as plist
✓ import * as plist from 'simple-plist';
✗ import plist from 'simple-plist'; // Incorrect default import
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 }
✓ import { readFileSync, writeFileSync } from 'simple-plist';
✗ const { readFileSync, writeFileSync } = require('simple-plist'); // CommonJS, not ESM
For specific synchronous file operations, named imports are efficient. Other common named exports include `readFile`, `writeFile`, `parse`, `stringify`, `readBinaryFileSync`, `writeBinaryFileSync`, etc.
require('simple-plist')
✓ const plist = require('simple-plist');
✗ import plist from 'simple-plist'; // Incompatible with CommonJS modules
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
✓ import { parse } from 'simple-plist';
✗ import { parse: parsePlist } from 'simple-plist'; // Unnecessary alias if not conflicting
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.
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.');
}
}
simple-plist --version
Errors
Common errors & fixes
TypeError: plist.readFileSync is not a function
Attempting to access a function (e.g., `readFileSync`) directly from a default import or incorrectly requiring the module in an ESM context.
fixEnsure 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'
The specified plist file does not exist at the provided path, or the path is incorrect.
fixVerify 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
The input string or file content is not a valid XML or binary plist format, or is malformed.
fixInspect 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.
Audit
Dependencies
plistrequiredCore dependency for parsing and building XML plist data.
bplist-parserrequiredCore dependency for parsing binary plist data.
bplist-creatorrequiredCore dependency for creating binary plist data.