クリップボード操作ライブラリの比較: clipboard-copy vs clipboard-polyfill

Web アプリケーションでテキストをクリップボードにコピーする機能は、ユーザー体験を向上させる上で非常に重要です。しかし、ブラウザ間の実装差やセキュリティ制限により、一貫した動作を保証するのは簡単ではありません。clipboard-copy と clipboard-polyfill は、この課題を解決するために設計された軽量な npm パッケージですが、アプローチとユースケースが異なります。以下では、実際の開発現場での使用観点から、両者の技術的違いを詳しく見ていきます。

🧰 基本的な使い方と API 設計

clipboard-copy は、単一の関数として設計されており、引数に文字列を渡すだけでクリップボードへのコピーを試みます。内部では、モダンブラウザの navigator.clipboard.writeText() を優先的に使用し、古い環境ではフォールバックとして <textarea> 要素を一時的に生成して document.execCommand('copy') を呼び出します。

// clipboard-copy の基本的な使用例
import copy from 'clipboard-copy';

await copy('コピーしたいテキスト');

clipboard-polyfill も同様に writeText() メソッドを提供しますが、API は Clipboard インターフェースに忠実になるよう設計されています。これは、将来的にネイティブ API に移行する際にコード変更を最小限に抑えることを意図しています。

// clipboard-polyfill の基本的な使用例
import { writeText } from 'clipboard-polyfill';

await writeText('コピーしたいテキスト');

両方とも Promise を返す非同期 API ですが、clipboard-copy は関数そのものがエントリーポイントであるのに対し、clipboard-polyfill は名前付きエクスポートを使用している点が異なります。

🌐 ブラウザサポートとフォールバック戦略

clipboard-copy は、可能な限りシンプルな実装を目指しており、navigator.clipboard が利用できない場合にのみ execCommand ベースのフォールバックを有効にします。ただし、execCommand は現在非推奨となっており、一部のモダンブラウザ（特に iOS Safari）では信頼性が低いことがあります。

clipboard-polyfill は、より積極的なポリフィル戦略を採用しています。たとえば、navigator.clipboard が存在しない環境だけでなく、パーミッションエラーが発生した場合にも自動的にフォールバックを試みます。さらに、clipboard-polyfill は text/plain 以外の MIME タイプにも対応できる拡張性を持っています（ただし、writeText の使用時はテキスト専用）。

// clipboard-polyfill は将来的に write() による複数フォーマット対応も可能
// 現在の writeText() は text/plain 専用

⚠️ エラーハンドリングとユーザーエクスペリエンス

clipboard-copy は、コピー操作が失敗した場合に例外をスローします。開発者はこれを try/catch でキャッチして、ユーザーにエラーメッセージを表示するなどの対応が必要です。

// clipboard-copy のエラーハンドリング
try {
  await copy('テキスト');
  console.log('コピー成功');
} catch (err) {
  console.error('コピー失敗:', err);
}

clipboard-polyfill も同様に Promise の reject でエラーを通知しますが、内部でより詳細なエラー原因を判別しようとします。たとえば、NotAllowedError（ユーザーの許可なしにコピーを試みた場合）や SecurityError（サンドボックス環境など）を区別して処理することが可能です。

// clipboard-polyfill のエラーハンドリング
try {
  await writeText('テキスト');
} catch (err) {
  if (err.name === 'NotAllowedError') {
    alert('クリップボードへのアクセスがブロックされました。');
  } else {
    alert('コピー中にエラーが発生しました。');
  }
}

📦 モジュール構成とバンドルサイズへの影響

clipboard-copy は非常にコンパクトで、1つのファイルにすべてのロジックが含まれています。依存関係はゼロであり、バンドルサイズを極限まで抑えたいプロジェクトに適しています。

clipboard-polyfill は、機能ごとにモジュールが分かれているため、ツリーシェイキングが効きやすい構造になっています。たとえば、writeText のみをインポートすれば、他の未使用の機能（例: readText）はバンドルに含まれません。

// clipboard-polyfill は必要な機能だけをインポート可能
import { writeText } from 'clipboard-polyfill/write-text';
// 上記のように特定のサブパスを指定することで、さらに軽量化可能

実際、clipboard-polyfill は公式ドキュメントで、使用する機能に応じて異なるエントリーポイントを推奨しています。これにより、不要なコードを完全に排除できます。

🛠 実際の開発シーンでの選定基準

シンプルなコピー機能だけで十分な場合

UI 上の「コピー」ボタンを実装するなど、単純なテキストコピーしか必要ない場合は、clipboard-copy が最適です。コードが短く、依存関係がなく、直感的に使えるため、小規模なプロジェクトや軽量なコンポーネントライブラリとの統合に向いています。

信頼性と将来性を重視する場合

企業向けアプリや、多様なブラウザ環境で確実に動作させる必要がある場合は、clipboard-polyfill を選ぶべきです。より堅牢なフォールバック機構と、ネイティブ API への移行を見据えた設計が、長期的なメンテナンスコストを下げてくれます。

🔁 非同期操作とユーザーフィードバック

どちらのパッケージも非同期操作のため、コピー中や成功後に UI を更新する必要があります。以下は React コンポーネントでの典型的な使用例です。

// clipboard-copy を使った React コンポーネント
import copy from 'clipboard-copy';

function CopyButton({ text }) {
  const [copied, setCopied] = useState(false);

  const handleClick = async () => {
    try {
      await copy(text);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch (err) {
      // エラーハンドリング
    }
  };

  return <button onClick={handleClick}>{copied ? 'コピー済み' : 'コピー'}</button>;
}

// clipboard-polyfill を使った React コンポーネント
import { writeText } from 'clipboard-polyfill';

function CopyButton({ text }) {
  const [copied, setCopied] = useState(false);

  const handleClick = async () => {
    try {
      await writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch (err) {
      // より詳細なエラーハンドリングが可能
    }
  };

  return <button onClick={handleClick}>{copied ? 'コピー済み' : 'コピー'}</button>;
}

見た目はほぼ同じですが、内部の信頼性とエラーハンドリングの粒度に差があります。

📌 まとめ：どちらを選ぶべきか

最終的な判断基準:

• 「すぐに動く軽量なコピー機能が欲しい」→ clipboard-copy
• 「あらゆる環境で確実に動作させたい」→ clipboard-polyfill

どちらも信頼できる選択肢ですが、プロジェクトの要件と保守方針に合わせて選ぶことが重要です。