pluginSsg

ページを静的HTMLとして出力するための必須プラグインです。JSX・TSX・Markdown・MDXからHTMLを生成し、ページから参照するCSS・JavaScript・画像も出力します。

以前のpluginMdx() pluginBundle() pluginEntry()の機能も含みます。

導入ははじめる、ページの作り方はファイルベースルーティングを参照してください。このページは設定値と公開APIの契約をまとめています。

Table of Contents

オプション

既定値
pluginSsg({
  src: ["src/pages/**/*.{tsx,jsx,mdx,md}"],
  srcBases: ["src/pages"],
  layout: "src/layouts/index.{tsx,jsx}",
  mdx: {
    frontmatter: {
      name: "metadata",
    },
    remarkPlugins: [],
    rehypePlugins: [],
  },
  bundle: {
    outName: "bundle",
  },
  removeImagePreload: true,
})

src

  • 型: string[]
  • デフォルト: ["src/pages/**/*.{tsx,jsx,mdx,md}"]

ページテンプレートをプロジェクトルート相対のglob形式で指定します。対象ファイルはViteの機能でglob importされます。従来の先頭スラッシュ付きパスも同じ場所として扱われます。

srcBases

  • 型: string[]
  • デフォルト: ["src/pages"]

ページのファイルパスからURLを決める際に、先頭から取り除くディレクトリをプロジェクトルート相対で指定します。例えばsrcBases: ["src/pages"]なら、src/pages/about.tsxからsrc/pagesと拡張子を除いて、URLは/aboutになります。従来の先頭スラッシュ付きパスも同じ場所として扱われます。

layout

  • 型: string
  • デフォルト: "src/layouts/index.{tsx,jsx}"

すべてのページテンプレートをラップするコンポーネントの場所をプロジェクトルート相対で指定します。対象ファイルはViteの機能でglob importされ最初に見つかったファイルが使用されます。従来の先頭スラッシュ付きパスも同じ場所として扱われます。

mdx

  • 型: false | (MdxCompileOptions & { frontmatter?: false | { name?: string } })
  • デフォルト: { frontmatter: { name: "metadata" }, remarkPlugins: [], rehypePlugins: [] }

MDX・Markdownの変換設定です。YAML/TOMLのフロントマターはfrontmatter.nameで指定した名前のMDX exportへ変換され、frontmatter: falseでフロントマター変換だけを無効化できます。YAMLは---、TOMLは+++で囲みます。MDX全体はデフォルトで有効です。無効にする場合はmdx: falseを指定します。srcを省略している場合、無効化に合わせて既定の探索対象もJSX・TSXだけになります。

bundle

  • 型: { outName: string }
  • デフォルト: { outName: "bundle" }

ページとレイアウトがimportするCSSをまとめ、参照する画像も出力します。outNameは、まとめたCSSのファイル名の基になる名前です。拡張子は含めず、例えばoutName: "site"なら、既定の出力設定ではassets/site-[hash].cssになります。CSS Modulesを使う場合は、生成HTMLとCSSで同じクラス名を使います。

removeImagePreload

  • 型: boolean
  • デフォルト: true

Reactのレンダラーの出力に含まれるlink[rel="preload"][as="image"]を、Head APIの合成前に除去します。開発時とビルド、通常ページとIslandの静的レンダリングで共通です。client:onlyの内容は静的レンダリングされません。falseにするとレンダラーの出力を保持します。

自動生成か手書きかを判定する設定ではありません。Layoutの<head>を含む通常のJSXへ直接書いた画像の先読みも除去対象です。明示的なpreloadを残す場合はHead APIを使ってください。フォントなど画像以外のリソースヒントは変更しません。

ページ

既定の探索対象はsrc/pages/**/*.{tsx,jsx,mdx,md}です。JSX・TSXではコンポーネントをdefault exportします。Markdown・MDXでは本文がページになります。

metadataをページデータとして読み込み、draft: trueのページを本番ビルドから除外します。Markdown・MDXのフロントマターは既定でmetadataになります。export名を変更した場合、ページデータへ渡すにはmetadataとしてもexportしてください。

静的データとルート生成

getStaticData()から{ props }または{ paths, props }の配列を返します。pathsは動的ファイル名のパラメーターと一致するキー、文字列の値を持ちます。

開発、ビルド、check、通常のinspectでページモジュールと取得関数を実行します。公開後のリクエストごとには実行しません。コード例はAPIによるページ生成を参照してください。

レイアウト

既定のファイルはsrc/layouts/index.{tsx,jsx}です。default exportのコンポーネントへ、ページデータとchildrenを渡します。metadataとgetStaticData()で共通データを指定できます。

ルートにhtmlを返す場合は、レイアウトのhtml head bodyを使います。それ以外は既定の構造で包みます。既定の言語はenです。レイアウトのhtmlまたはHead.htmlAttributesで変更してください。

ディレクトリごとのレイアウトが自動的に入れ子になる仕組みはありません。構成例はレイアウトを参照してください。

minista/headからimportし、ページやコンポーネントからhead要素を追加します。使い方はHeadを参照してください。

項目用途
childrentitle meta link script styleなど
htmlAttributeshtml要素の属性
bodyAttributesbody要素の属性
子要素のkey同じキーの要素を後のものへ差し替える

レイアウトへ後から適用し、title・charset・viewportが重複する場合はHead側を優先します。charsetとviewportがない場合は既定値を補い、headの先頭へこの順で配置します。

publicのファイル参照

public/logo.svgはJSXやMDXで/logo.svgと指定します。ビルド時にpluginSsg()が実在するpublicファイルを判定し、参照URLへViteのbaseを自動適用します。追加オプションは不要です。publicDirの変更とpublicDir: falseにも対応します。

baseindex.htmldemos/index.html
//logo.svg/logo.svg
/test//test/logo.svg/test/logo.svg
./または空文字logo.svg../logo.svg
https://cdn.example.com/https://cdn.example.com/logo.svghttps://cdn.example.com/logo.svg

補正するHTMLの要素・属性は次のとおりです。いずれも、/で始まるURLが実在するpublicファイルを指す場合にbaseを反映します。

HTML要素URLを書く属性用途の例
imgsrc、srcset画像とサイズ別の候補
sourcesrc、srcset動画・音声・画像の候補
linkhref、imagesrcsetCSS・favicon・画像の先読み
scriptsrcJavaScriptの読み込み
videosrc、poster動画と再生前の画像
audio、tracksrc音声・字幕の読み込み
SVGのimage、usehref、xlink:href画像・シンボルの参照
objectdata外部ファイルの埋め込み
embed、inputsrc外部ファイル・画像ボタン
ahrefPDFなどpublicファイルへのリンク
対象のmetacontentOGP画像など。対象は下記を参照

metaは、propertyがog:image、og:image:url、og:image:secure_url、og:audio、og:audio:secure_url、og:video、og:video:secure_urlの場合に対応します。nameがtwitter:image、msapplication-TileImage、msapplication-square70x70logo、msapplication-square150x150logo、msapplication-wide310x150logo、msapplication-square310x310logo、msapplication-configの場合も対応します。

style属性と<style>内の通常のurl()にも対応します。/logo.svg?v=1#markのクエリとフラグメント、srcsetの1xや640wなどの記述子は、そのまま残します。

次の参照は自動補正しません。

  • 外部URL、data URL、#iconのようなフラグメントだけの参照、./logo.svgなどの相対URL
  • 通常のページリンク、独自のdata属性
  • public内のCSS・JavaScript・JSONなどに書かれたURL。ファイル本体は無加工でコピーします。
  • style属性や<style>内の、CSSのエスケープを含むURL、@importの文字列、image-set()の文字列
  • ブラウザのJavaScriptで組み立てるURL
  • Island内部の参照。client:onlyのフォールバックも含みます。

Islandでは、静的HTMLとブラウザ側の初回表示で同じURLを使う必要があります。baseを含むURLを用意し、propsとして渡すなどして両方の表示を揃えてください。

HTMLからのアセット参照

HTML属性から参照するCSS・JavaScript・画像をビルド対象にします。導入例はCSS・JS・TSのエントリーを参照してください。

ページやLayoutのモジュールのimportから参照するCSS・画像も引き続きSSGが出力します。

対象の要素と属性

プロジェクトルート内の元ファイルをEntryとしてバンドルする場合、収集と書換えは次の対象に限定します。publicファイルは前述の「publicのファイル参照」を参照してください。

要素属性値の扱い
linkhref単一URL。relでは限定しない
scriptsrc単一URL
imgsrc単一URL
img、sourcesrcset各候補のURL。1xや640wは保持
SVGのusehref単一URL。シンボルのフラグメントは保持

/で始まるプロジェクトルート相対の参照だけを収集し、ルート内に実ファイルがあるものをバンドルします。https://、//cdn.example.com/、data:、#icon、./image.pngなどは変更しません。単一URL内のカンマと、srcsetのdata URL内のカンマも保持します。srcsetのURLと記述子の間には空白を入れてください。

meta[content]、video[poster]、a[href]、source[src]、SVGのimage[href]/use[xlink:href]、任意の要素の同名属性は対象外です。例えば<meta property="og:image" content="/src/image.png" />だけでは画像を出力しません。これらにはSSGでimportした画像URLかpublicアセットのURLを指定してください。

/public.svgとして参照するpublic/public.svgはViteがコピーし、SSGが参照URLへbaseを適用します。ルートにもpublicにも実ファイルがない参照はそのまま残し、欠落診断もしません。同じURLに対応するファイルをプロジェクトルートとpublicの両方へ置くと、Entryはルート側をバンドルするため、この配置は避けてください。

/src/app.ts?v=1#startはsrc/app.tsをバンドルし、出力URLに?v=1#startを保持します。クエリはViteの?raw/?urlなどのモジュール変換指定としては渡しません。出力URLはViteのbaseに従い、/site/、CDNの絶対URL、./や空文字によるページ相対URLに対応します。入力の/src/…にはbaseを付けません。

エントリーがimportするCSSは、そのエントリーを参照するページにだけ挿入します。同じURLのstylesheetが既にある場合や、複数エントリーが同じCSSを使う場合は重複挿入しません。クエリ/フラグメントが異なるstylesheet URLは別扱いです。

公開型

Metadata、PageProps、LayoutProps、StaticData、GetStaticDataはminista/typesから利用します。ページやレイアウトにはurl title draftなどが渡されます。レイアウトにはchildrenも含みます。

独自項目の型定義とモジュール拡張はTypeScriptを参照してください。型を追加しただけでHTML要素が生成されるわけではありません。