HTML

Parcel は、HTML を初期状態からファーストクラスでサポートしています。HTML ファイルは Parcel に提供するエントリファイルとなることが多く、JavaScript、CSS、画像、他のページへのリンクなど、すべての依存関係がそこから追跡され、アプリ全体がビルドされます。

依存関係

Parcel は、HTML 内の他のファイル（例：<script>、<img>、<video>、<meta property="og:image">）へのほとんどの参照を検出し、それらも処理します。これらの参照は、正しい出力ファイルにリンクするように書き換えられます。

ファイル名は現在の HTML ファイルを基準に解決されますが、絶対指定子とチルダ指定子を使用することもできます。詳細は依存関係の解決を参照してください。

スタイルシート

<link rel="stylesheet"> 要素を使用して、HTML からスタイルシートを参照できます。CSS ファイル、または SASS、Less、Stylus など、CSS にコンパイルされる他のファイルを参照できます。

index.html

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="./style.less" />
  </head>
  <body>
    <h1>My Parcel app</h1>
  </body>
</html>

style.less

h1 {
  color: darkslategray;
}

Parcel による CSS の処理方法の詳細は、CSS ドキュメントを参照してください。

スクリプト

<script> 要素を使用して、HTML からスクリプトファイルを参照できます。JavaScript ファイル、または TypeScript、JSX、CoffeeScript など、JavaScript にコンパイルされる他のファイルを参照できます。

index.html

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="app.ts" />
  </head>
  <body>
    <h1>My Parcel app</h1>
  </body>
</html>

app.ts

console.log('Hello world!')

type="module" 属性は、ファイルが ES モジュールまたは CommonJS ファイルであることを示すために使用されます。省略した場合、参照ファイルは従来のスクリプトとして扱われます。詳細は、従来のスクリプトを参照してください。

<script type="module"> が使用されている場合、ブラウザターゲットの一部が ES モジュールをサポートしていない場合、Parcel は自動的に <script nomodule> バージョンも生成します。詳細は、差分バンドリングを参照してください。

Parcel は、<script> 要素の async 属性と defer 属性もサポートしています。スクリプトが async の場合、実行時に任意の順序でロードされる可能性があります。そのため、Parcel は非同期スクリプトを「分離」として扱います。これは、非同期スクリプトがページ上の他のスクリプトと依存関係を共有できないことを意味し、モジュールの重複が発生する可能性があります。このため、特定の状況を除いて、async スクリプトは避ける方が良いでしょう。

defer属性はasync（レンダリングブロッキングなし）と同様の効果がありますが、スクリプトがHTMLファイルで定義されている順序で実行されることを保証します。 <script type="module">を使用する場合、deferは自動的に有効になり、宣言する必要はありません。

詳細については、<script> 要素の MDN ドキュメントと、Parcel による JavaScript の処理方法の詳細については JavaScript ドキュメントを参照してください。

画像

Parcel は、<img> 要素によって参照される画像をサポートしています。src 属性を使用して、画像ファイルを参照できます。

<img src="image.jpg" alt="An image">

Parcel は、srcset 属性もサポートしており、さまざまなサイズまたは解像度の画像の複数のバージョンを参照できます。

<img src="logo@1x.png" srcset="logo@2x.png 2x" alt="logo">

さらに、Parcel は、<picture> 要素をサポートしており、<source> 要素を介して複数の代替画像を提供するためのさらに高い柔軟性を提供します。

Parcel の画像トランスフォーマーを使用して、単一のソースファイルから画像の複数のバージョンを生成することもできます。これは、クエリパラメータを使用して、ソース画像の変換とサイズ変更を行う幅、高さ、および形式を指定することによって行われます。

<picture>
  <source type="image/webp" srcset="image.jpg?as=webp&width=400, image.jpg?as=webp&width=800 2x">
  <source type="image/jpeg" srcset="image.jpg?width=400, image.jpg?width=800 2x">
  <img src="image.jpg?width=400" width="400">
</picture>

リンクと iframe

Parcel は、<a> 要素をサポートしており、HTML ファイルから別のページにリンクできます。

<a href="other.html">Other page</a>

<iframe> 要素を使用して、HTML ページを別のページに埋め込むことができます。

<iframe src="iframe.html"></iframe>

HTML ファイルから参照される他のアセットは、コンパイルされたファイル名にデフォルトでコンテンツハッシュが含まれますが、<a> または <iframe> 要素によって参照されるファイルには含まれません。これは、これらの URL が通常は人間が判読できる形式であり、時間の経過とともに安定した名前を必要とするためです。バンドルの命名は、ネーミングプラグインによってオーバーライドできます。

ビデオ、オーディオ、その他の資産

<video>、<audio>、<track>、<embed>、<object> 要素がサポートされています。参照される URL は Parcel によって処理され、コンテンツハッシュを含むように書き換えられます。

Open Graph と Schema.org のメタデータ

Parcel は、Open Graph、Twitter カード、VK、Schema.org、Microsoft ピン留めサイトのメタデータを、<meta> タグを使用して定義されたものをサポートしています。これらの要素で参照される画像やその他の URL は Parcel によって処理され、コンテンツハッシュを含むように書き換えられます。

<meta property="og:image" content="100x100.png" />

JSON-LD

Parcel は、<script> タグを介して HTML に埋め込まれた JSON-LD メタデータをサポートしています。JSON-LD で参照される画像やその他の URL は Parcel によって処理され、コンテンツハッシュを含むように書き換えられます。これは、必要に応じてプロジェクトに自動的にインストールされる @parcel/transformer-jsonld プラグインによって処理されます。

この例では、logo オブジェクトから参照される画像は Parcel によって処理されます。

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "LocalBusiness",
  "name": "Joe's Pizza",
  "description": "Delicious pizza for over 30 years.",
  "telephone": "555-111-2345",
  "openingHours": "Mo,Tu,We,Th,Fr 09:00-17:00",
  "logo": {
    "@type": "ImageObject",
    "url": "images/logo.png",
    "width": 180,
    "height": 120
  }
}
</script>

Web マニフェスト

<link rel="manifest"> 要素は、Web マニフェストを参照するためにサポートされています。これは、アプリに関するさまざまなメタデータを含む JSON ファイルであり、ユーザーのホーム画面またはデスクトップにインストールできるようにします。Parcel は、このファイルの icons キーと screenshots キーで参照される URL を処理します。Web マニフェストは、.json ファイルまたは .webmanifest ファイルのいずれかで記述できます。

<link rel="manifest" href="manifest.json">

インラインスクリプトとスタイル

テキストコンテンツを含む <script> タグと <style> タグもスタンドアロンファイルと同様に処理され、生成されたバンドルは HTML ファイルに再び挿入されます。スクリプトタグの type="module" 属性は、上記の外部スクリプトの場合と同様に機能します。ただし、ブラウザターゲットの一部が ES モジュールをネイティブにサポートしていない場合、Parcel はインラインスクリプトを非モジュールスクリプトにのみコンパイルし、生成される HTML を小さく保つために <script type="module"> を出力しません。

index.html

<!DOCTYPE html>
<html>
  <body>
    <style>
      @import "./style.scss";
    </style>
    <script type="module">
      import value from "./other.ts";
      console.log(value);
    </script>
  </body>
</html>

注：大きなインラインスクリプト/スタイルは（認識される）ロード速度に悪影響を与える可能性があるため、控えめに使用してください。

インライン `style` 属性

style 属性は、任意の HTML 要素で使用して、CSS スタイルを定義できます。Parcel はインライン CSS を処理し、結果を style 属性に再び挿入します。これには、背景画像などの参照される URL に従うこと、およびターゲットブラウザに合わせて最新の CSS を変換することが含まれます。

<div style="background: url(background.jpg)">Hello!</div>

インライン SVG

ParcelはHTMLにインラインSVGをサポートしています。<image>要素で参照される画像と、<use>要素で参照される依存関係もサポートされており、SVG内のインラインスクリプトとスタイルも上記のように処理されます。

<!DOCTYPE html>
<html>
  <body>
    <svg xmlns:xlink="http://www.w3.org/1999/xlink">
      <rect x="10" y="10" width="50" height="50" fill="red" />
      <use xlink:href="icon.svg"/>
    </svg>
  </body>
</html>

並列スクリプトとスタイル

スクリプトまたはスタイルを参照する場合、ParcelはコンパイルされたHTMLファイルに別の依存ファイルを挿入する必要がある場合があります。たとえば、CSSファイルをインポートするJavaScriptファイルを参照する場合、Parcelは<head>に<link>要素を挿入して、JavaScriptと並行してこのスタイルシートを読み込みます。

index.html

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="app.js"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

app.js

import './app.css';

let app = document.createElement('div');
app.className = 'app';
app.textContent = 'My Parcel app!';
root.appendChild(app);

app.css

.app {
  background: red;
}

コンパイルされたHTML

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" src="app.f8e9c6.css">
    <script type="module" src="app.26fce9.js"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

これはスクリプトでも発生する可能性があります。たとえば、2つのページが同じJavaScriptライブラリ（ReactやLodashなど）に依存している場合、それらは独自のバンドルに分割され、個別にロードされる場合があります。Parcelは、この「共有バンドル」を並行してロードするために、コンパイルされたHTMLに<script>タグを挿入します。詳細はコード分割を参照してください。

PostHTML

PostHTMLは、プラグインを使用してHTMLを変換するためのツールです。PostHTMLは、次のいずれかの名前を使用して設定ファイルを作成することで設定できます。.posthtmlrc（JSON、**強く**推奨）、.posthtmlrc.js、.posthtmlrc.mjs、.posthtmlrc.cjs、posthtml.config.js、posthtml.config.mjs、またはposthtml.config.cjs。

アプリケーションにプラグインをインストールする

yarn add posthtml-doctype --dev

次に、設定ファイルを作成します

.posthtmlrc

{
  "plugins": {
    "posthtml-doctype": { "doctype": "HTML 5" }
  }
}

プラグインはpluginsオブジェクトにキーとして指定され、オプションはオブジェクト値を使用して定義されます。プラグインにオプションがない場合は、空のオブジェクトに設定してください。

この例では、posthtml-includeを使用して別のHTMLファイルをインライン化しています。

.posthtmlrc

{
  "plugins": {
    "posthtml-include": {}
  }
}

index.html

<html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <include src="header.html"></include>
    <main>My content</main>
  </body>
</html>

header.html

<header>This is my header</header>

posthtml.config.js

設定オプションとして関数を渡す必要があるプラグイン、またはprocess.env.NODE_ENVに基づいてプラグインを設定するには、.posthtmlrcの代わりにposthtml.config.jsファイルを使用して設定する必要があります。

**注意**: 可能であれば、JavaScript設定ファイルの使用は避けてください。これらはParcelのキャッシュの効率を低下させ、Parcelを再起動するたびにすべてのHTMLファイルが再コンパイルされることを意味します。これを回避するには、JSONベースの設定形式（例：.posthtmlrc）を使用してください。

この例では、posthtml-shortenを使用して、カスタム短縮関数を使用してURLを短縮しています。

yarn add posthtml-shorten --dev

posthtml.config.js

module.exports = {
  plugins: {
    "posthtml-shorten": {
      shortener: {
        process: function (url) {
          return new Promise((resolve, reject) => {
            resolve(url.replace(".html", ""));
          });
        },
      },
      tag: ["a"], // Allowed tags for URL shortening
      attribute: ["href"], // Attributes to replace on the elements
    },
  },
};

index.html

<html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <a href="http://example.com/test.html">Example</a>
  </body>
</html>

本番環境

本番モードでは、Parcelにはコードのファイルサイズを削減するための最適化が含まれています。この仕組みの詳細については、本番環境を参照してください。

縮小化

本番モードでは、Parcelはバンドルのファイルサイズを縮小するためにコードを自動的に縮小します。デフォルトでは、Parcelはhtmlnanoを使用してHTMLの縮小を実行します。htmlnanoを設定するには、プロジェクトのルートディレクトリに.htmlnanorcまたは.htmlnanorc.jsonファイルを作成します。

たとえば、HTMLコメントを保持するには

.htmlnanorc

{
  "removeComments": false
}

または、SVG要素を縮小しないようにするには

.htmlnanorc

{
  "minifySvg": false
}

**注意**: .htmlnanorc.js、.htmlnanorc.mjs、.htmlnanorc.cjs、htmlnano.config.js、htmlnano.config.mjs、およびhtmlnano.config.cjsもJavaScriptベースの設定でサポートされていますが、Parcelのキャッシュの効率が低下するため、可能な限り避ける必要があります。代わりにJSONベースの設定形式を使用してください。

依存関係

スタイルシート

スクリプト

画像

リンクと iframe

ビデオ、オーディオ、その他の資産

Open Graph と Schema.org のメタデータ

JSON-LD

Web マニフェスト

インラインスクリプトとスタイル

インライン style 属性

インライン SVG

並列スクリプトとスタイル

PostHTML

posthtml.config.js

本番環境

縮小化

インライン `style` 属性