A JOURNAL OF SOFTWARE PRACTICE

Mosslog

HOME / その他 / 2026

ブログサイト作ってみた（機能実装編）

主要機能の設計と実装 〜Markdown・CRUD・検索・画像アップロード〜

2026 年 4 月 29 日·0 分·#個人開発#Next.js#web

はじめに

前回の記事で、ブログサイトの全体像を紹介しました。 今回は、具体的な機能実装について、なぜその設計にしたかという視点を中心に書いていきます。

扱う機能は以下の4つです。

  1. 1. マークダウンエディタとプレビュー: 記事執筆の核となる機能

  2. 2. 記事管理画面（CRUD）: 記事の作成・編集・削除

  3. 3. 検索・フィルタリング機能: 記事を探しやすくする機能

  4. 4. 画像アップロード機能: アイキャッチ画像の管理

機能1: マークダウンエディタとプレビュー

ブログサイトで記事を書く際、マークダウン形式で書けることは必須だと考えました。 理由はシンプルで、普段から技術的なメモをマークダウンで書いている習慣があったからです。HTMLやリッチテキストエディタよりも、プレーンテキストに近いマークダウンで書ける方が、自分のイメージに合っていました。

今回実装する機能としては以下になります。

  1. - ライブプレビュー機能: 編集中にリアルタイムでプレビューを確認できる

  2. - シンタックスハイライト: コードブロックが読みやすくなる　

  3. - コードコピーボタン: 読者がコードをコピーしやすくする

  4. - リンクアイコン表示: 外部リンクかどうかが一目で分かる

技術選定

マークダウンの処理にはunifiedというエコシステムを使うことにしましたunifiedは、テキストを処理するためのツールでremark（マークダウン処理）rehype（HTML処理）を組み合わせて使います。

なぜunifiedを選んだかというと、プラグイン形式で機能を追加できる点が魅力的だったからです。マークダウンからHTMLへの変換だけでなく、シンタックスハイライトや、カスタム機能（コードコピーボタンやリンクアイコン）をプラグインとして追加できます。 処理の流れは以下のようになります。 

Markdown 
→ remark-parse (マークダウンを解析) 
→ remark-gfm (GitHub Flavored Markdown対応) 
→ remark-rehype (HTML構造に変換) 
→ rehype-raw (HTMLタグを許可) 
→ rehype-slug (見出しにIDを付与) 
→ rehype-link-icon (外部リンクにアイコン追加) 
→ rehype-highlight (シンタックスハイライト) 
→ rehype-code-copy (コードコピーボタン追加) 
→ rehype-sanitize (XSS対策) 
→ rehype-stringify (HTML文字列に変換) 
→ HTML

プラグインの順序も重要です。

例えばrehype-sanitizeは最後に実行します。 これは他のプラグイン（シンタックスハイライトやコードコピーボタン）が追加した要素や属性を、サニタイズ時に削除しないようにするためです。

実装時の課題

実装で苦労した点がいくつかありました。 XSS対策とのバランス: セキュリティのためrehype-sanitizeでサニタイズしますが、シンタックスハイライト用のクラスhljs-*など）やコードコピーボタン用の属性は残したいという課題です。

これは、デフォルトのスキーマをカスタマイズして、必要な属性のみを許可する方式にしました。

コードコピーボタンの実装: rehype-code-copyというカスタムプラグインを作りましたが、これは単にHTMLを追加するだけで、実際のコピー機能はJavaScriptで実装する必要があります。プレビュー表示時に、コードコピーボタンにイベントリスナーを追加する処理も必要でした。

プレビューのパフォーマンス: マークダウンを編集するたびにHTMLに変換するので、長い記事だと処理が重くなる可能性があります。現状useEffectで処理していますが、将来的にはデバウンス処理を追加することも検討しています。

学んだこと

マークダウンの処理は、単純にHTMLに変換するだけでは済まないことが分かりました。 セキュリティ、UX、パフォーマンスのバランスを取る必要があります。 プラグイン形式unifiedを使うことで、機能を段階的に追加できたのは良かったです。

機能2: 記事管理画面（CRUD）

記事の作成・編集・削除を管理する画面が必要でした。 最初はシンプルなフォームから始めましたが、以下の機能を段階的に追加していきました。

  1. - 記事の作成・編集・削除: 基本機能

  2. - 下書き機能: 記事を途中で保存して、後で続きを書けるようにする

  3. - タグ管理: 記事を分類しやすくする

  4. - 画像アップロード: アイキャッチ画像を設定できるようにする

API設計

APIには、Next.js API Routesではなく**Hono**を使うことにしました。 理由は、Edge Runtimeで動かすためです。Cloudflare Workers上でNext.js API Routesを使うと、一部の機能が制限されるため、Honoの方が柔軟に対応できます。

APIの設計では、以下の点を意識しました。

  1. - 入力バリデーション: Zodで型安全なバリデーションを行う

  2. - レートリミット: 管理APIは30リクエスト/分に制限

  3. - エラーハンドリング: 統一されたエラーレスポンス

特にバリデーションは重要です。

フロントエンドでもチェックしますが、サーバー側でも必ず検証します。 Zodを使うことで、TypeScriptの型とバリデーションロジックを統一できました。

アーキテクチャの考え方

記事管理機能の実装では、クリーンアーキテクチャを意識しました。

  1. - プレゼンテーション層: 機能コンポーネント（UI）

  2. - ユースケース層: 記事の作成・更新・削除のロジック

  3. - インフラ層: D1データベースへのアクセス

各層が独立していることで、テストが書きやすくなりました。 例えば、データベースを使わずにユースケース層のテストを書けます。

実装時の課題

フォーム管理: React Hook Formを使いましたが、マークダウンのような大量のテキストを扱う場合、状態管理が複雑になりがちです。特に、プレビュー機能と連動させる際に、状態の同期が課題でした。

画像アップロードのタイミング: 記事を保存する前に画像をアップロードする必要がありますが、記事IDが確定するまではアップロードできません。そこで、記事を先に保存してから画像をアップロードする方式にしました。

エラーハンドリング: ネットワークエラーやバリデーションエラーなど、様々なエラーケースに対応する必要がありました。エラーメッセージをユーザーに分かりやすく伝えるために、トースト通知を使いました。

学んだこと

管理画面の実装では、UXとセキュリティのバランスが重要だと感じました。 使いやすさを追求しつつ、適切なバリデーションとレートリミットを設ける必要があります。 また、クリーンアーキテクチャを意識することで、コードの見通しが良くなったと思います。

機能3: 検索・フィルタリング機能

記事が増えてきたとき、過去の記事を探しやすくする機能が必要だと考えました。 検索とフィルタリングの両方を実装しました。

  1. - キーワード検索: タイトルやタグで検索

  2. - タグフィルタリング: タグをクリックして記事を絞り込む

  3. - ページネーション: 記事が多くなっても一覧が見やすく

検索機能は、最初はシンプルな文字列検索から始めました。 将来的には全文検索（Full-Text Search）も検討していますが、現時点ではタイトルとタグでの検索で十分だと考えています。

実装の考え方

検索とフィルタリングは、URLのクエリパラメータで管理することにしました。 理由は、検索結果のURLを共有できるようにするためです。 例えば、「Next.jsの記事一覧」のURLを誰かに共有すれば、同じ結果を表示できます。 URLの構造は以下のようになります。

  1. - 通常の記事一覧: /articles

  2. - タグフィルタ: /articles?tag=Next.js

  3. - キーワード検索: /articles?q=React

  4. - ページネーション: /articles?page=2

実装時の課題

D1での検索クエリ: SQLiteベースのD1では、全文検索（FTS）を使うこともできますが、現時点ではシンプルLIKE検索を使っています。記事が増えてきたら、パフォーマンスを考慮してFTSに移行することも検討しています。

ページネーションの実装: 総記事数を取得して総ページ数を計算する必要がありますが、検索やフィルタリングが適用されている場合、正しく計算する必要があります。そのため、検索条件に応じて総記事数を再計算する処理が必要でした。

状態管理: 検索クエリとページネーションの状態を、URLパラメータと同期させる必要があります。Next.jsuseSearchParamsを使いましたが、サーバーコンポーネントとクライアントコンポーネントの間での状態同期が少し複雑でした。

学んだこと

検索機能は、シンプルに見えて意外と複雑です。URLの管理、クエリの最適化、状態の同期など、様々な考慮点があります。しかし、URLで状態を管理することで、ブラウザの戻る/進むボタンも自然に使えるようになり、UXが向上しました。

機能4: 画像アップロード機能

記事にアイキャッチ画像を設定できるようにしたいと考えました。 画像の保存先として、**Cloudflare R2**を使うことにしました。 理由は、Cloudflare Workersと統合しやすく、エグレス費用がかからないためです。

要件としては以下を挙げました：

- Presigned URLによるアップロード: セキュアにアップロードできるようにする - 画像の削除機能: 不要になった画像を削除できるようにする

- ファイルタイプ・サイズの検証: 不正なファイルをアップロードさせない

実装の考え方

画像アップロードには、**Presigned URL**を使う方式にしました。これは、AWS S3互換のAPIで、一時的なURLを生成してクライアントから直接R2にアップロードできる方式です。サーバーを経由せずにアップロードできるため、パフォーマンス面でも有利です。

流れは以下のようになります。

  1. 1. クライアント: 画像ファイルを選択

  2. 2. サーバー: Presigned URLを生成して返す

  3. 3. クライアント: Presigned URLを使ってR2に直接アップロード

  4. 4. サーバー: アップロード完了後、画像URLをデータベースに保存

実装時の課題

記事IDと画像の紐付け: 記事を保存する前に画像をアップロードしたい場合、記事IDがまだ決まっていません。そこで、記事を先に保存してIDを確定させてから、画像をアップロードする方式にしました。

画像削除の実装: 画像を削除する際、データベースからURLを削除するだけでなく、R2からも実際のファイルを削除する必要があります。画像を削除するAPIエンドポイントを作り、R2からも削除する処理を実装しました。

エラーハンドリング: 画像アップロードは非同期処理が多いため、エラーハンドリングが複雑になりがちです。特に、ネットワークエラーやファイルサイズ制限などのエラーケースに対応する必要がありました。

学んだこと

画像アップロードは、単純にアップロードするだけでなく、セキュリティやパフォーマンスを考慮する必要があります。Presigned URLを使うことで、セキュアかつ効率的にアップロードできるようになりました。また、画像の削除処理も忘れずに実装することが重要だと感じました。

終わりに

この記事では、主要な機能について、なぜその設計にしたかという視点を中心に書きました。技術的な詳細よりも、設計の考え方や試行錯誤のログに焦点を当てたつもりです。 実装してみて分かったことは、**シンプルに見える機能でも、様々な考慮点がある**ということです。マークダウンの処理一つ取っても、セキュリティ、UX、パフォーマンスのバランスを取る必要があります。

次回は、実際の開発で遭遇した課題と解決方法について詳しく書く予定です。Next.js App Routerとの格闘や、Edge Runtimeの制約など、技術的な深掘りに入っていきます。