@c-time/frelio-gentl

FrelioDataJson からテンプレートを使って HTML を生成するライブラリ。

Frelio とは

Frelio は GitHub + Cloudflare で動くヘッドレス CMS。コンテンツは GitHub リポジトリに JSON ファイルとして保存され、静的サイト生成（SSG）パイプラインで HTML に変換し、Cloudflare Pages にデプロイする。

管理画面（React）で記事を編集
        ↓
GitHub リポジトリにコンテンツ JSON を保存
        ↓
GitHub Actions で SSG パイプラインを実行
        ↓
生成された HTML を Cloudflare Pages にデプロイ

バックエンドサーバーは不要。管理画面はブラウザから直接 GitHub GraphQL API を呼び出す。

ビルドパイプライン

SSG パイプラインは 3 フェーズで構成される。このパッケージは Phase 2 を担当する。

Phase 1: data-json-generator
  コンテンツ JSON + スキーマ定義 → FrelioDataJson[]（中間データ）

Phase 2: frelio-gentl                    ← このパッケージ
  FrelioDataJson[] + HTML テンプレート → HTML ファイル

Phase 3: Deployer
  生成された HTML → Cloudflare Pages

FrelioDataJson とは

Phase 1 が出力する中間データ形式。「どのテンプレートに、どのデータを流し込んで、どのパスに出力するか」を 1 ファイルずつ定義する。

{
  "type": "create",
  "template": "article/detail.html",
  "outputFile": "articles/my-article.html",
  "data": {
    "title": "記事タイトル",
    "body": "<p>本文の HTML</p>",
    "tags": [{ "name": "TypeScript" }, { "name": "CMS" }]
  }
}

type: "delete" の場合は、以前生成されたファイルの削除を意味する（増分ビルド対応）。

このパッケージの役割

FrelioDataJson[] を受け取り、テンプレートエンジン @c-time/gentl で HTML テンプレートとデータを結合し、最終的な HTML を出力する。

• テンプレートエンジン: @c-time/gentl — DOM ベースで data-gen-* 属性によりデータをバインド
• DOM 環境: happy-dom — ブラウザ不要の軽量 DOM 実装
• エラー耐性: 一部が失敗しても最後まで処理を継続し、結果をレポートに記録
• 増分ビルド対応: type: "create" と type: "delete" の両方を処理

<!-- テンプレート例 -->
<template data-gen-scope="">
  <h1 data-gen-text="title">Default Title</h1>
  <div data-gen-html="body">Default Body</div>
  <ul>
    <template data-gen-repeat="tags" data-gen-repeat-name="tag">
      <li data-gen-text="tag.name">Tag</li>
    </template>
  </ul>
</template>

インストール

npm install @c-time/frelio-gentl

使用例

import { generateHtml, NodeFileSystem } from '@c-time/frelio-gentl'
import type { FrelioDataJson } from '@c-time/frelio-data-json'
import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from 'fs'
import { dirname, join } from 'path'

// data-json ファイルを読み込み
const dataJsons: FrelioDataJson[] = [
  JSON.parse(readFileSync('frelio-data/generated/data-json/articles/my-article.json', 'utf-8')),
]

// HTML を生成
const result = await generateHtml({
  dataJsons,
  templateRootPath: 'frelio-data/site/templates',
  fileSystem: new NodeFileSystem(),
  options: {
    logLevel: 'info',
  },
})

// ファイルに出力
for (const output of result.outputs) {
  const fullPath = join('dist', output.outputPath)

  if (output.status === 'deleted') {
    if (existsSync(fullPath)) unlinkSync(fullPath)
  } else {
    mkdirSync(dirname(fullPath), { recursive: true })
    writeFileSync(fullPath, output.html)
  }
}

// レポート
console.log(`Created: ${result.report.stats.created}`)
console.log(`Deleted: ${result.report.stats.deleted}`)
console.log(`Errors: ${result.report.stats.errors}`)

テンプレートディレクティブ

| ディレクティブ | 説明 | 例 | |---------------|------|-----| | data-gen-text | プレーンテキスト挿入 | data-gen-text="title" | | data-gen-html | HTML 挿入 | data-gen-html="body" | | data-gen-repeat | 配列反復 | data-gen-repeat="items" | | data-gen-if | 条件表示 | data-gen-if="isPublished" | | data-gen-attrs | 動的属性 | data-gen-attrs="src:imageUrl,alt:title" | | data-gen-include | 外部ファイル読み込み | data-gen-include="header.html" | | data-gen-json | JSON シリアライズ | data-gen-json="metadata" | | data-gen-scope | スコープ指定 | data-gen-scope="navigation" | | data-gen-comment | 要素削除 | data-gen-comment="true" |

処理順序: comment → if → include → repeat → text/html → json → attrs

API リファレンス

generateHtml(input)

メイン関数。FrelioDataJson から HTML を生成。

function generateHtml(input: GenerateHtmlInput): Promise<GenerateHtmlResult>

入力

| パラメータ | 型 | 説明 | |-----------|---|------| | dataJsons | FrelioDataJson[] | 入力データ | | templateRootPath | string | テンプレートルートパス | | fileSystem | FileSystemPort | ファイルシステム | | options | GenerateHtmlOptions | オプション |

オプション

| オプション | 型 | デフォルト | 説明 | |-----------|---|-----------|------| | logLevel | 'debug' \| 'info' \| 'quiet' | 'info' | ログレベル | | cacheTemplates | boolean | true | テンプレートキャッシュ | | rootParserType | string | 'htmlDocument' | DOM パースモード |

NodeFileSystem

Node.js の FileSystemPort 実装。

HappyDomEnvironment

happy-dom ベースの DOM 環境アダプタ（内部使用）。

エラーハンドリング

一部のテンプレートが処理できなくても最後まで継続し、エラーをレポートに記録。

| コード | 説明 | |--------|------| | TEMPLATE_NOT_FOUND | テンプレートファイルが見つからない | | RENDER_ERROR | レンダリング中にエラーが発生 | | INVALID_DATA | データが不正 |

gentl 内部の警告（データ参照失敗等）は report.warnings に記録される。

依存関係

@c-time/frelio-gentl
├── @c-time/frelio-data-json    # 入力型
├── @c-time/gentl               # テンプレートエンジン
└── happy-dom                   # DOM 環境（軽量、高速）

ライセンス

MIT