APIリファレンス

まずcreateDecks(config)から始める

導入手順で作るsrc/decks.tsが、生成物と公開APIの境界になります。デッキを表示するだけなら、このページの低レベルAPIを直接組み合わせる必要はありません。

hono-decks: HonoアプリとWorkerで使う実行時APIです。通常はこのエントリーを使います。
hono-decks/advanced: データ取得、ルーター、レンダラーを独自に組み立てるための低レベルAPIです。
hono-decks/node: ファイル読み込みとコンパイルに使います。ビルド処理だけで読み込み、Workerには含めません。
hono-decks/client: Islandを有効にするためのエントリーです。通常は生成されたクライアントコードが使用します。

導入手順から始める →

実行時API

HonoアプリやWorkerでは、hono-decksから読み込みます。まず生成されたcreateDecks(config)を使い、必要な機能が足りない場合に限って個別のAPIを利用してください。

defineDecksConfig

hono-decks

CLIと実行時で共有する設定を型付きで定義します。

使う場面公開パス、ビルド対象、実行時の設定を1ファイルにまとめるとき。

Import + signature

import { defineDecksConfig } from "hono-decks"

defineDecksConfig(config: DecksConfig): DecksConfig

ConfiguredDecks

hono-decks

生成されたcreateDecks(config)が返す、設定済みのAPIです。

使う場面ルート、独自画面、URLを同じ設定から利用するとき。

Import + signature

import type { ConfiguredDecks } from "hono-decks"

interface ConfiguredDecks { mountPath; source; router(); context(); paths(slug) }

createDeckPaths

hono-decks

1つのデッキに対応する公開URLをまとめて生成します。

使う場面createDecks(config)を使わず、URL一覧だけが必要なとき。

Import + signature

import { createDeckPaths } from "hono-decks"

createDeckPaths(mountPath, slug): DeckPaths

decksRouter

hono-decks/advanced

独自のDeckSourceから低レベルのルーターを構築します。

使う場面生成コードを使わず、デッキの取得からルーティングまでを独自に組み立てるとき。

Import + signature

import { decksRouter } from "hono-decks/advanced"

decksRouter(options: DecksRouterOptions): Hono

レンダリングと拡張

標準UIの一部を使う、独自UIへ差し替える、アセットの取得元を変える場合に使います。

createDeckViewerParts

hono-decks/advanced

ビューアーを構成する部品を個別に取得します。

使う場面標準のビューアーを使わず、独自のレイアウトを組むとき。

Import + signature

import { createDeckViewerParts } from "hono-decks/advanced"

createDeckViewerParts(input): Promise<DeckViewerParts>

createDeckViewerEmbed

hono-decks

必要なCSSとスクリプトを含む埋め込み用ビューアーを作成します。

使う場面独自画面にビューアーを直接組み込むとき。外部iframe用のルートにはembedオプションを使います。

Import + signature

import { createDeckViewerEmbed } from "hono-decks"

createDeckViewerEmbed(input: DeckViewerEmbedOptions): Promise<DeckViewerEmbed>

withR2Assets

hono-decks

生成済みアセットをR2から取得するDeckSourceを作成します。

使う場面MDXの相対パスを変えずに、画像などの配信元をCloudflare R2へ移すとき。

Import + signature

import { withR2Assets } from "hono-decks"

withR2Assets(source: DeckSource, options: R2AssetSourceOptions): DeckSource

defineSlideComponents

hono-decks

標準コンポーネントとアプリ独自のコンポーネントを型付きで登録します。

使う場面複数デッキへ共通のコンポーネントを登録、または標準コンポーネントを差し替えるとき。デッキ固有の部品はcomponents/に置きます。

Import + signature

import { defineSlideComponents } from "hono-decks"

defineSlideComponents(input: Record<string, SlideComponentInput>): SlideComponentRegistry

renderCompiledDeckAsync

hono-decks/advanced

コンパイル済みデッキを直接描画します。

使う場面標準ルーターを使わず、描画処理を独自に組み立てるとき。

Import + signature

import { renderCompiledDeckAsync } from "hono-decks/advanced"

renderCompiledDeckAsync(deck: CompiledDeck, input?): Promise<string>

設定とモデルの型

公開画面、HTMLの共通設定、独自のDeckSourceを型付きで定義するときに使います。

DeckViewerOpenGraphOptions

hono-decks

ビューアーのOpen Graph画像とTwitter Card画像を、標準パスまたは関数で設定します。

使う場面ビルド時に生成したOGP画像や外部CDNの画像を、ビューアーのSNS向けメタデータに設定するとき。

Import + signature

import type { DeckViewerOpenGraphOptions } from "hono-decks"

interface DeckViewerOpenGraphOptions { imagePath?: string | (({ deck, paths }) => MaybePromise<string | undefined>) }

DecksRouterPagesOptions

hono-decks

一覧、ビューアー、印刷、発表画面などの表示をリクエストごとに設定します。

使う場面不要な公開画面を無効化する、または認証や環境に応じて表示を切り替えるとき。

Import + signature

import type { DecksRouterPagesOptions } from "hono-decks"

interface DecksRouterPagesOptions { index?; viewer?; render?; print?; presentation?; presenter? }

DeckRouteSurfaceInput

hono-decks

各ルートを有効にするか判断する関数へ、Honoのコンテキスト、デッキ、公開パス、開発モードの値を渡します。

使う場面pagesの判定関数を別ファイルに定義し、入力型を明示するとき。

Import + signature

import type { DeckRouteSurfaceInput } from "hono-decks"

interface DeckRouteSurfaceInput { c; surface; mountPath; dev; deck?; slug? }

DeckDocumentOptions

hono-decks

HTMLの言語、nonce、head要素と、画面ごとの上書きを定義します。

使う場面生成するすべてのHTMLに、lang、CSPのnonce、head要素をまとめて適用するとき。

Import + signature

import type { DeckDocumentOptions } from "hono-decks"

interface DeckDocumentOptions extends DeckDocumentPageOptions { surfaces? }

DeckExternalEmbedOptions

hono-decks

外部サイトへ埋め込むためのページと許可するオリジンを設定します。

使う場面別オリジンのサイトへデッキをiframeで埋め込み、許可先とビューアーを設定するとき。

Import + signature

import type { DeckExternalEmbedOptions } from "hono-decks"

interface DeckExternalEmbedOptions { frameAncestors?; document?; viewer? }

DeckSource

hono-decks

デッキやアセットの取得方法を定義します。ローカル、R2などの保存先をルーターから分離できます。

使う場面生成済みマニフェスト以外からデッキを取得する、または保存先を独自実装するとき。

Import + signature

import type { DeckSource } from "hono-decks"

interface DeckSource { listDecks(c); getCompiledDeck(c, slug); getAsset?(c, slug, path) }

Node.jsとクライアント向けエントリー

ファイル操作とコンパイルはNode.js向けエントリーから、Islandの有効化はクライアント向けエントリーから読み込みます。

compileDecks

hono-decks/node

ファイルシステム上のデッキをコンパイルし、マニフェストとモジュールを出力します。

使う場面独自のビルドスクリプトやプラグインからコンパイラーを呼ぶとき。通常はCLIのhono-decks compileを使います。

Import + signature

import { compileDecks } from "hono-decks/node"

compileDecks(input: CompileDecksInput): Promise<DeckManifest>

createLocalDeckIO

hono-decks/node

開発時に使う未変換デッキの読み書きを、実行時のDeckSourceから分離します。

使う場面デッキ編集・プレビュー機能を持つ独自の開発ツールを作るとき。通常の配信コードでは使いません。

Import + signature

import { createLocalDeckIO } from "hono-decks/node"

createLocalDeckIO(input: CreateLocalDeckIOInput): LocalDeckIO

hydrateSlideIslands

hono-decks/client

生成されたクライアントエントリーから、操作を伴うIslandを有効にします。

使う場面クライアントコードの配信処理を独自に構築するとき。通常は生成されたエントリーが自動で呼び出します。

Import + signature

import { hydrateSlideIslands } from "hono-decks/client"

hydrateSlideIslands(input: HydrateSlideIslandsInput): void