pluginSsg

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

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

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

オプション
- src
- srcBases
- layout
- mdx
- bundle
- removeImagePreload
ページ
静的データとルート生成
レイアウト
Head
publicのファイル参照
HTMLからのアセット参照
- 対象の要素と属性
公開型

オプション

既定値

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に変換する際に省くプロジェクトルート相対パス。前方一致で削除されます。従来の先頭スラッシュ付きパスも同じ場所として扱われます。

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" }

ページとレイアウトから参照されたCSS・画像を描画結果と同じ変換結果から出力します。outNameはCSSをまとめるエントリー名（拡張子なし）に使用されます。CSS ModulesもHTMLと同じクラス名で出力します。

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で変更してください。

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

Head

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

項目	用途
`children`	`title` `meta` `link` `script` `style`など
`htmlAttributes`	`html`要素の属性
`bodyAttributes`	`body`要素の属性
子要素の`key`	同じキーの要素を後のものへ差し替える

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

publicのファイル参照

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

`base`	`index.html`	`demos/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.svg`	`https://cdn.example.com/logo.svg`

画像のsrc／srcset、linkのhref／imagesrcset、scriptのsrc、動画・音声・trackのsrc、動画のposter、SVGのimage／useのhref／xlink:href、object[data]、embed[src]、input[src]が対象です。og:image／og:audio／og:videoとURL関連の派生property、twitter:image、Microsoftのtile画像・設定のmetaも補正します。

a[href]はpublic実ファイルへのリンクだけ補正します。style属性と<style>内の通常のurl()にも対応します。/logo.svg?v=1#markのクエリ／フラグメント、srcsetの記述子は保持します。外部URL、data URL、フラグメントのみ、./などの相対参照、通常のページリンク、独自data属性は変更しません。

publicファイル本体は無加工でコピーします。public内のCSS・JS・JSONなどに書かれたURL、inline CSSのescape付きURL・@import文字列・image-set文字列、ブラウザ実行時のURLは自動補正しません。Island内部（client:onlyのフォールバックを含む）もSSRとクライアントの一致を保つため対象外です。必要なURLはSSRとクライアントへ同じpropsとして渡してください。

HTMLからのアセット参照

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

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

対象の要素と属性

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

要素	属性	値の扱い
`link`	`href`	単一URL。`rel`では限定しない
`script`	`src`	単一URL
`img`	`src`	単一URL
`img`、`source`	`srcset`	各候補のURL。`1x`や`640w`は保持
SVGの`use`	`href`	単一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要素が生成されるわけではありません。