parcel-bundler

Parcel Bundler

Parcel（Web 向けのゼロコンフィグビルドツール）のエキスパートとして、Parcel プロジェクトで作業する際は以下のガイドラインに従ってください。

基本原則

• デフォルトでゼロコンフィグ — Parcel はすぐに使えます
• 依存関係の検出とインストールを自動で行います
• ホットモジュール置換に対応した開発サーバーを内蔵しています
• Rust ベースのコンパイラーによるネイティブなパフォーマンスを実現します
• コード分割と最適化を自動で行います

プロジェクト構成

project/
├── src/
│   ├── index.html        # HTML entry point
│   ├── index.js          # JavaScript entry
│   ├── styles.css        # Stylesheets
│   └── assets/           # Images, fonts, etc.
├── dist/                 # Build output (auto-generated)
├── .parcelrc             # Optional configuration
└── package.json

はじめに

基本的な使い方

# Development with hot reload
parcel src/index.html

# Production build
parcel build src/index.html

package.json のスクリプト

{
  "scripts": {
    "dev": "parcel src/index.html",
    "build": "parcel build src/index.html",
    "clean": "rm -rf dist .parcel-cache"
  },
  "source": "src/index.html"
}

エントリーポイント

HTML エントリー

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="./styles.css">
</head>
<body>
  <div id="app"></div>
  <script type="module" src="./index.js"></script>
</body>
</html>

JavaScript エントリー

parcel build src/index.js --dist-dir lib

複数のエントリーポイント

parcel build src/index.html src/admin.html

サポートされている言語とファイル形式

Parcel は標準で以下をサポートしています。

• JavaScript/TypeScript：.js、.jsx、.ts、.tsx、.mjs
• スタイル：.css、.scss、.sass、.less、.styl
• HTML：.html、.htm
• 画像：.png、.jpg、.gif、.svg、.webp
• フォント：.woff、.woff2、.ttf、.otf、.eot
• データ：.json、.yaml、.toml、.xml
• WebAssembly：.wasm

設定（必要な場合）

.parcelrc

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["@parcel/transformer-svg-react"]
  },
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

package.json のターゲット

{
  "targets": {
    "main": {
      "source": "src/index.js",
      "distDir": "dist",
      "context": "browser",
      "outputFormat": "esm"
    }
  }
}

TypeScript のサポート

自動設定

Parcel は TypeScript を自動で処理します。.ts または .tsx ファイルを使うだけです。

tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "isolatedModules": true
  }
}

React のサポート

自動 JSX

// Parcel handles JSX automatically
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

CSS とスタイリング

CSS のインポート

import './styles.css';

CSS Modules

import * as styles from './Button.module.css';

function Button() {
  return <button className={styles.primary}>Click me</button>;
}

Sass/SCSS

import './styles.scss';

.scss ファイルを使用すると、Parcel は sass を自動でインストールします。

アセットの処理

アセットのインポート

import logo from './logo.png';
import data from './data.json';

// Use in JSX
<img src={logo} alt="Logo" />

URL 参照

const imageUrl = new URL('./image.png', import.meta.url);

コード分割

動的インポート

// Automatic code splitting
const LazyComponent = React.lazy(() => import('./LazyComponent'));

// Or manual
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

共有バンドル

Parcel は、複数のエントリーポイントで使用されるコードの共有バンドルを自動で作成します。

環境変数

.env ファイル

# .env
API_URL=https://api.example.com

# .env.production
API_URL=https://api.production.com

コード内での使用

const apiUrl = process.env.API_URL;

package.json での定義

{
  "targets": {
    "default": {
      "publicUrl": "/my-app/"
    }
  }
}

開発サーバー

デフォルト設定

parcel src/index.html
# Serves at http://localhost:1234

カスタムポート

parcel src/index.html --port 3000

HTTPS

parcel src/index.html --https

API リクエストのプロキシ

{
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://localhost:8080"
      }
    }
  }
}

本番ビルド

基本的なビルド

parcel build src/index.html

出力設定

parcel build src/index.html --dist-dir build --public-url /app/

ソースマップなし

parcel build src/index.html --no-source-maps

最適化

自動最適化

Parcel は以下を自動で行います。

• JavaScript、CSS、HTML、SVG を最小化します
• 画像を圧縮します
• キャッシュ用のコンテンツハッシュを生成します
• 未使用のコードをツリーシェイキングします
• モジュールをスコープホイストします

バンドル分析

npm install -D parcel-reporter-bundle-analyzer

# Add to .parcelrc
{
  "extends": "@parcel/config-default",
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

キャッシュ

Parcel は積極的にキャッシュを使用します。

# Clear cache
rm -rf .parcel-cache

# Or
parcel build --no-cache

プラグイン開発

プラグインの種類

• トランスフォーマー：ソースファイルを変換します
• リゾルバー：カスタムのモジュール解決を行います
• バンドラー：カスタムのバンドル処理を行います
• ネーマー：カスタムの出力名を設定します
• パッケージャー：バンドルをパッケージ化します
• オプティマイザー：バンドルを最適化します
• レポーター：カスタムのビルドレポートを作成します

プラグインのルール

1. ステートレス：内部状態を持たないようにします
2. 純粋：同じ入力からは同じ出力を生成します
3. 副作用なし：外部状態を変更しません

ライブラリー開発

Package.json の設定

{
  "name": "my-library",
  "source": "src/index.ts",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "types": "dist/types.d.ts",
  "targets": {
    "main": {
      "outputFormat": "commonjs"
    },
    "module": {
      "outputFormat": "esmodule"
    },
    "types": {
      "source": "src/index.ts"
    }
  }
}

ベストプラクティス

推奨事項

• ゼロコンフィグから始めます
• アセットの最適化は Parcel に任せます
• コード分割には動的インポートを使用します
• 依存関係の自動インストールを活用します
• コンポーネントのスタイルには CSS Modules を使用します

避けるべきこと

• デフォルト設定で十分な場合に、過剰な設定を行うこと
• Parcel の規約に逆らうこと
• Parcel が処理する内容を手動で最適化すること
• ビルドの警告やエラーを無視すること

一般的なパターン

シングルページアプリケーション

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./index.tsx"></script>
</body>
</html>

静的サイト

parcel build src/*.html

Web Worker

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module'
});

トラブルシューティング

キャッシュのクリア

rm -rf .parcel-cache dist

詳細な出力

parcel build --log-level verbose

デバッグモード

DEBUG=parcel:* parcel build

他のバンドラーからの移行

• webpack.config.js などの設定ファイルを削除します
• ローダーやプラグインの依存関係を削除します
• 必要に応じてインポート文を更新します
• Parcel が必要な依存関係を自動でインストールします