{"id":10671,"library":"copy-paste","title":"copy-paste Clipboard Utility","description":"copy-paste is a Node.js utility designed to provide read/write access to the system clipboard across different operating systems. It achieves cross-platform compatibility by wrapping native command-line tools: `pbcopy` and `pbpaste` for macOS, `xclip` for Linux and BSD systems, and `clip` for Windows. This abstraction allows developers to interact with the clipboard using a unified JavaScript API. The package offers both a traditional callback-based interface for asynchronous operations and a modern Promise-based API for `async/await` patterns, accessible via a submodule. It is currently at version 2.2.0 and, while not actively undergoing rapid feature development, it remains a maintained package for fundamental clipboard interactions in Node.js environments. Its primary differentiator is its robust cross-platform wrapper for underlying system utilities, abstracting away the OS-specific commands.","status":"maintenance","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/xavi-/node-copy-paste","tags":["javascript","copy","paste","copy and paste","clipboard"],"install":[{"cmd":"npm install copy-paste","lang":"bash","label":"npm"},{"cmd":"yarn add copy-paste","lang":"bash","label":"yarn"},{"cmd":"pnpm add copy-paste","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The core API of `copy-paste` uses CommonJS `require()` for named exports. It does not natively support ES Module `import` syntax.","wrong":"import { copy, paste } from 'copy-paste';","symbol":"copy, paste","correct":"const { copy, paste } = require('copy-paste');"},{"note":"The promise-based API is exposed via a separate CommonJS submodule at `copy-paste/promises`. Destructuring is also common: `const { copy, paste } = require('copy-paste/promises');`.","wrong":"import clipboard from 'copy-paste/promises';","symbol":"clipboard (promise API)","correct":"const clipboard = require('copy-paste/promises');"},{"note":"This method adds `copy` and `paste` functions to the global namespace. While functional, it's generally discouraged in modern Node.js development in favor of explicit module imports.","symbol":"global()","correct":"require('copy-paste').global();"}],"quickstart":{"code":"import { setTimeout } from 'timers/promises';\n\n// Use the promise-based API for modern async/await patterns\nconst { copy, paste } = require('copy-paste/promises');\n\nasync function runClipboardExample() {\n  try {\n    console.log('Copying text...');\n    await copy('Hello from copy-paste! ' + new Date().toISOString());\n    console.log('Text copied.');\n\n    await setTimeout(100);\n\n    console.log('Pasting text...');\n    const text = await paste();\n    console.log('Clipboard content:', text);\n\n    console.log('Copying JSON object...');\n    const data = { message: 'Clipboard data', timestamp: Date.now(), source: 'copy-paste' };\n    await copy.json(data);\n    console.log('JSON object stringified and copied.');\n\n    await setTimeout(100);\n\n    console.log('Pasting JSON string...');\n    const jsonText = await paste();\n    console.log('Clipboard JSON string:', jsonText);\n    const parsedData = JSON.parse(jsonText);\n    console.log('Parsed JSON object:', parsedData);\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n    // Provide guidance for common errors\n    if (error.message.includes('command not found')) {\n      console.error('Hint: Ensure `xclip` (Linux), `pbcopy`/`pbpaste` (macOS), or `clip` (Windows) is installed and in your PATH.');\n    }\n  }\n}\n\nrunClipboardExample();","lang":"javascript","description":"This quickstart demonstrates the asynchronous copy and paste operations using the promise-based API, including copying plain text and stringified JSON, then pasting and parsing the content. It also includes basic error handling for missing system dependencies."},"warnings":[{"fix":"Ensure the required system clipboard utility is installed and available in your system's PATH. For Linux, `xclip` is commonly needed (e.g., `sudo apt-get install xclip` or `sudo yum install xclip`).","message":"This package relies on external system utilities (`pbcopy`/`pbpaste` on macOS, `xclip` on Linux/BSD, `clip` on Windows) which might not be installed by default or configured correctly on all systems. Absence of these tools will lead to runtime errors when attempting clipboard operations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `const clipboard = require('copy-paste');` (or `require('copy-paste/promises')`) to import the package. If your project is pure ESM, you might need to use dynamic `import()` for CommonJS modules or transpile your code.","message":"The `copy-paste` package is CommonJS-only and does not natively support ES Module `import` syntax. Attempting to `import` it directly in a pure ESM Node.js environment will result in a `SyntaxError` or `ERR_REQUIRE_ESM`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Prefer importing `copy` and `paste` functions directly using `const { copy, paste } = require('copy-paste');` to maintain module scope and avoid global side effects.","message":"Using `require('copy-paste').global()` pollutes the global namespace with `copy` and `paste` functions, which is generally considered an anti-pattern in modern JavaScript development and can lead to naming conflicts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When retrieving content copied with `copy.json`, manually parse the result using `JSON.parse(text)` after pasting if you need to reconstitute the original object.","message":"The `copy.json(obj)` method stringifies the provided JavaScript object to a JSON string before copying it to the clipboard. Pasting this content will yield the JSON string, not the original JavaScript object.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the `xclip` utility on your Linux system. For Debian/Ubuntu-based systems: `sudo apt-get install xclip`. For RHEL/Fedora-based systems: `sudo yum install xclip`.","cause":"The `copy-paste` package requires external system utilities to function. On Linux, `xclip` or `xsel` is necessary and was not found in the system's PATH.","error":"Error: 'xclip' command not found. Please install 'xclip' or 'xsel' to enable clipboard support."},{"fix":"Use CommonJS `require()` syntax instead: `const { copy, paste } = require('copy-paste');` or `const clipboard = require('copy-paste/promises');`.","cause":"This error occurs when attempting to use ES Module `import` syntax (`import { copy } from 'copy-paste';`) with this CommonJS-only package in an ESM context.","error":"SyntaxError: Named export 'copy' not found. The requested module 'copy-paste' does not provide an export named 'copy'"},{"fix":"Ensure you correctly import the functions before use, e.g., `const { copy, paste } = require('copy-paste');` or `const clipboard = require('copy-paste/promises');`.","cause":"The `copy` or `paste` functions were called without being properly imported or destructured from the `require('copy-paste')` object, meaning they are undefined in the current scope.","error":"TypeError: copy is not a function"}],"ecosystem":"npm"}