copy-paste Clipboard Utility

Common errors

• Error: 'xclip' command not found. Please install 'xclip' or 'xsel' to enable clipboard support.

  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.
  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`.

• SyntaxError: Named export 'copy' not found. The requested module 'copy-paste' does not provide an export named 'copy'

  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.
  fix Use CommonJS `require()` syntax instead: `const { copy, paste } = require('copy-paste');` or `const clipboard = require('copy-paste/promises');`.

• TypeError: copy is not a function

  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.
  fix Ensure you correctly import the functions before use, e.g., `const { copy, paste } = require('copy-paste');` or `const clipboard = require('copy-paste/promises');`.

Warnings

• gotcha 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.
  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`).
• breaking 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`.
  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.
• gotcha 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.
  Fix: Prefer importing `copy` and `paste` functions directly using `const { copy, paste } = require('copy-paste');` to maintain module scope and avoid global side effects.
• gotcha 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.
  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.

Install

• npm install copy-paste npm
• yarn add copy-paste yarn
• pnpm add copy-paste pnpm

Imports

• copy, paste
  wrong:

  import { copy, paste } from 'copy-paste';

  correct:

  const { copy, paste } = require('copy-paste');

  The core API of `copy-paste` uses CommonJS `require()` for named exports. It does not natively support ES Module `import` syntax.
• clipboard (promise API)
  wrong:

  import clipboard from 'copy-paste/promises';

  correct:

  const clipboard = require('copy-paste/promises');

  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');`.
• global()

  require('copy-paste').global();

  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.

Quickstart

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.

import { setTimeout } from 'timers/promises';

// Use the promise-based API for modern async/await patterns
const { copy, paste } = require('copy-paste/promises');

async function runClipboardExample() {
  try {
    console.log('Copying text...');
    await copy('Hello from copy-paste! ' + new Date().toISOString());
    console.log('Text copied.');

    await setTimeout(100);

    console.log('Pasting text...');
    const text = await paste();
    console.log('Clipboard content:', text);

    console.log('Copying JSON object...');
    const data = { message: 'Clipboard data', timestamp: Date.now(), source: 'copy-paste' };
    await copy.json(data);
    console.log('JSON object stringified and copied.');

    await setTimeout(100);

    console.log('Pasting JSON string...');
    const jsonText = await paste();
    console.log('Clipboard JSON string:', jsonText);
    const parsedData = JSON.parse(jsonText);
    console.log('Parsed JSON object:', parsedData);

  } catch (error) {
    console.error('An error occurred:', error.message);
    // Provide guidance for common errors
    if (error.message.includes('command not found')) {
      console.error('Hint: Ensure `xclip` (Linux), `pbcopy`/`pbpaste` (macOS), or `clip` (Windows) is installed and in your PATH.');
    }
  }
}

runClipboardExample();