{"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,"search_vec":"'2.2.0':100 'abstract':55,135 'access':17,91 'achiev':27 'across':22 'activ':104 'allow':56 'api':67,87 'async/await':89 'asynchron':79 'away':136 'base':76,86 'bsd':48 'callback':75 'callback-bas':74 'clip':51 'clipboard':4,21,62,116,148 'command':36,141 'command-lin':35 'compat':31 'copi':2,7,143,145 'copy-past':1,6 'cross':29,128 'cross-platform':28,127 'current':97 'design':13 'develop':57,108 'differ':23 'differenti':123 'environ':120 'featur':107 'fundament':115 'interact':59,117 'interfac':77 'javascript':66,142 'line':37 'linux':46 'maco':43 'maintain':112 'modern':83 'nativ':34 'node.js':11,119 'offer':70 'oper':24,80 'os':139 'os-specif':138 'packag':69,113 'past':3,8,144,147 'pattern':90 'pbcopi':39 'pbpast':41 'platform':30,129 'primari':122 'promis':85 'promise-bas':84 'provid':15 'rapid':106 'read/write':16 'remain':110 'robust':126 'specif':140 'submodul':94 'system':20,25,49,133 'tool':38 'tradit':73 'under':132 'undergo':105 'unifi':65 'use':63 'util':5,12,134 'version':99 'via':92 'window':53 'wrap':33 'wrapper':130 'xclip':44","created_at":"2026-04-19T13:34:01.475595+00:00","updated_at":"2026-04-19T13:34:01.475595+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/xavi-/node-copy-paste","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/copy-paste","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}