unpkg.com の使い方 / npm にパッケージを公開してCDN配信する方法【初心者向け】

unpkg.com は npm 上の全パッケージをそのまま CDN 配信するサービスです。URLのルールを覚えれば、任意のパッケージを即座に利用できます。この記事では URL の読み方から本番環境での注意点、自作ライブラリをnpmに公開し、unpkg.comのURLで配信できるようにする手順：package.jsonの設定、npm publish、バージョンアップの方法まで、初めて公開する方向けにまとめています。

基本的な使い方

従来の「自社サーバーにファイルを置く」方式から unpkg.com に切り替えるのは、src を書き換えるだけです。

<!-- 従来の方法：自社サーバーにファイルを配置 -->
<script src="/js/library.js"></script>

<!-- unpkg.com を使う方法：CDN 経由で配信 -->
<script src="https://unpkg.com/library@1.0.0/dist/library.js"></script>

URL の構造

https://unpkg.com/{パッケージ名}@{バージョン}/{ファイルパス}

実例で読み解く

https://unpkg.com/react@18.2.0/umd/react.production.min.js
                  ↑       ↑      ↑
              パッケージ名  バージョン  npm パッケージ内のファイルパス

パッケージ内のどのファイルを指定するかは、npm のページか package.json の main フィールドで確認できます。ファイルパスを省略すると main フィールドで指定されたデフォルトファイルが返されます。

バージョン指定の方法

完全固定（本番環境での推奨）

<script src="https://unpkg.com/react@18.2.0/umd/react.production.min.js"></script>

パッチバージョンまで固定します。破壊的変更が混入しないため、本番環境では必ずこの形式を使います。

マイナーバージョンまで固定

<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>

18.x.x の最新を自動取得します。マイナーアップデートを追いかけたい場合に使いますが、本番環境での使用は慎重に。

常に最新（本番環境では非推奨）

<script src="https://unpkg.com/react/umd/react.production.min.js"></script>

バージョンを省略すると常に最新版が返ります。開発・確認目的に限定してください。

よく使うライブラリの記述例

<!-- jQuery -->
<script src="https://unpkg.com/jquery@3.7.1/dist/jquery.min.js"></script>

<!-- Vue.js -->
<script src="https://unpkg.com/vue@3.4.0/dist/vue.global.prod.js"></script>

<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://unpkg.com/bootstrap@5.3.2/dist/css/bootstrap.min.css">

<!-- Swiper -->
<link rel="stylesheet" href="https://unpkg.com/swiper@11.0.5/swiper-bundle.min.css">
<script src="https://unpkg.com/swiper@11.0.5/swiper-bundle.min.js"></script>

使用時の注意点

注意点1：バージョン指定は必須（本番環境）

<!-- ❌ NG：バージョン未指定 -->
<script src="https://unpkg.com/library"></script>

<!-- ✅ OK：バージョン固定 -->
<script src="https://unpkg.com/library@1.2.3/dist/library.min.js"></script>

バージョンを省略すると、ライブラリ側が破壊的変更を含む更新をリリースした瞬間にサイトが壊れる可能性があります。

注意点2：重要なビジネスロジックには使用しない

CDN は外部サービスです。以下の用途には unpkg.com ではなく自社サーバーを使用してください。

独自開発の重要なビジネスロジック
機密情報を含むスクリプト
サービスの根幹を支える処理

unpkg.com が適している用途：

jQuery・React・Vue.js などの OSS ライブラリ
Bootstrap・Tailwind CSS などのフレームワーク
Font Awesome などのアイコンライブラリ

注意点3：フォールバック（代替手段）の準備

外部 CDN に頼る場合、万が一の障害に備えてフォールバックを設定することを推奨します。

<!-- CDN から読み込み -->
<script src="https://unpkg.com/jquery@3.7.1/dist/jquery.min.js"></script>

<!-- CDN 失敗時は自社サーバーから読み込み -->
<script>
  if (!window.jQuery) {
    document.write('<script src="/js/jquery.min.js"></script>');
  }
</script>

ただし unpkg.com の実際の稼働率は 99.99% 以上（Cloudflare インフラ）のため、業務用途であっても過剰に心配する必要はありません。

パッケージが見つからない・URLが分からないとき

https://unpkg.com/{パッケージ名}/

末尾に / を付けてブラウザで開くと、パッケージ内のファイル一覧が表示されます。どのファイルを指定すればいいか分からないときに便利です。

# 例: react のファイル一覧を見る
https://unpkg.com/react@18.2.0/

npmパッケージの公開方法

Node.js と npm のインストール

Node.js 公式サイトからインストールしてください。npm は自動的にインストールされます。

# バージョン確認
node -v
npm -v

npm アカウントの作成

npmjs.com でアカウントを作成してください。パッケージの公開に必要です。

1. プロジェクトの初期化

# プロジェクトディレクトリを作成
mkdir my-package
cd my-package

# package.json を生成（対話形式）
npm init

# または全てデフォルトで生成
npm init -y

2. package.json の設定

npm 公開で最も重要なのが package.json の設定です。

{
  "name": "my-package",
  "version": "1.0.0",
  "description": "My awesome library",
  "main": "dist/my-package.js",
  "files": [
    "dist",
    "css",
    "js"
  ],
  "keywords": ["library", "cdn"],
  "author": "Your Name",
  "license": "MIT"
}

重要な設定項目

フィールド	説明	注意
`name`	パッケージ名	npm で一意である必要があります
`version`	バージョン番号	Semantic Versioning（後述）に従う
`main`	エントリーポイント	unpkg.com でパスを省略した場合に返されるファイル
`files`	公開するファイル・ディレクトリ	指定しないと全ファイルが公開されます
`license`	ライセンス	MIT か ISC が一般的

パッケージ名の注意

npm 全体で一意である必要があります
既存パッケージと被らない名前にしてください（事前に npmjs.com で検索）
スコープ付き名前（例：@yourname/my-package）にすることで名前衝突を避けられます

3. 公開するファイルを準備する

files フィールドで指定したディレクトリ・ファイルだけが npm に公開されます。ソースコード（src/）は公開せず、ビルド済みのファイル（dist/）だけを公開するのが一般的です。

my-package/
├── src/            ← 開発用ソース（公開しない）
│   └── index.js
├── dist/           ← ビルド済みファイル（公開する）
│   ├── my-package.js
│   └── my-package.min.js
├── css/            ← CSS があれば（公開する）
│   └── my-package.css
├── package.json
└── README.md

.npmignore ファイルを作成することで、公開から除外するファイルを細かく指定することもできます。

4. npm へログイン・公開

# npm アカウントでログイン（初回のみ）
npm login

# パッケージを公開
npm publish

スコープ付きパッケージを公開する場合

# スコープ付きパッケージはデフォルトでプライベート扱いになるため、
# public フラグが必要
npm publish --access public

5. unpkg.com で確認

公開後、数分以内に unpkg.com で利用可能になります。

# ファイル一覧を確認
https://unpkg.com/my-package@1.0.0/

# main フィールドで指定したファイルへの直接アクセス
https://unpkg.com/my-package@1.0.0

# 特定ファイルへのアクセス
https://unpkg.com/my-package@1.0.0/dist/my-package.min.js

ブラウザで開いて、ファイルの内容が表示されれば成功です。

6. バージョンアップ時の手順

Semantic Versioning（バージョン番号の付け方）

npm は MAJOR.MINOR.PATCH の形式でバージョン管理します。

種別	バージョン変化	使うタイミング
`patch`	`1.0.0` → `1.0.1`	バグ修正のみ
`minor`	`1.0.0` → `1.1.0`	後方互換性のある機能追加
`major`	`1.0.0` → `2.0.0`	破壊的変更を含む

バージョンを上げて再公開

# patch バージョンを上げる（1.0.0 → 1.0.1）
npm version patch

# minor バージョンを上げる（1.0.0 → 1.1.0）
npm version minor

# major バージョンを上げる（1.0.0 → 2.0.0）
npm version major

# 再公開
npm publish

npm version コマンドは package.json のバージョン番号を自動更新し、Git タグも作成します。

よくあるエラーと対処

`You must be logged in to publish packages.`

npm login

でログインしてから再実行してください。

`Package name too similar to existing packages.`

パッケージ名が既存のものと類似しすぎています。名前を変更するか、スコープ（@yourname/）を付けてください。

`You do not have permission to publish "xxx".`

そのパッケージ名はすでに他のユーザーが公有しています。別の名前を使用してください。

`403 Forbidden` （再公開時）

一度公開したバージョンは再公開できません。npm version patch でバージョンを上げてから npm publish してください。

まとめ

npm への公開手順は5ステップです。

npm init でプロジェクト初期化
package.json の name・main・files を設定
ビルド済みファイルを dist/ に用意
npm login → npm publish
https://unpkg.com/{パッケージ名}@{バージョン}/ で確認

一度公開してしまえば、バージョンアップは npm version patch && npm publish の2コマンドで完結します。unpkg.com 側は npm と自動同期されるため、追加の設定は一切不要です。