【ITニュース解説】DevLog: Building GritPath OS - Day 1 Using Convex

新しいプロジェクト「GritPath OS」の開発が始まった。このプロジェクトは、企業が事業の青写真を作成し、レベルアップするためのプラットフォームを目指している。今回の記事では、その開発初日の記録として、使用する技術スタックの紹介から、特にデータベースであるConvexのセットアップと基本的な使い方について詳しく解説する。システムエンジニアを目指す初心者でも理解しやすいように、具体的な手順と概念を順を追って説明していく。

まず、このプロジェクトで採用している主要な技術スタックについて説明する。フロントエンド開発には、ReactをベースにしたフレームワークであるNext.jsを使用する。これにより、サーバーサイドレンダリングなどの恩恵を受けつつ、効率的にユーザーインターフェースを構築できる。UIコンポーネントとスタイリングには、デザインシステムを提供するShadcnとユーティリティファーストのCSSフレームワークであるTailwind CSSを組み合わせる。データベースとバックエンドの機能にはConvexを採用する。これは、リアルタイム性と開発のしやすさが特徴のサービスだ。ユーザー認証にはClerk Authを使用し、アプリケーションのセキュリティを確保する。開発言語としては、コードの信頼性と保守性を高めるためにTypeScriptを使う。現時点では完全に実装されていないが、Pythonも一部で利用される予定だ。そして、最終的なアプリケーションのデプロイには、Next.jsとの連携が容易なVercelを利用する。

次に、これらの技術を実際に使い始めるための環境構築から説明する。 まず、Next.jsのアプリケーションを作成する。コマンドラインで「npx create-next-app@latest my-app」と入力すると、いくつかの設定に関する質問がされる。「TypeScriptを使いますか？」「Tailwind CSSを使いますか？」「App Routerを使いますか？」といった質問に対しては、それぞれ「Yes」を選択していく。これにより、最新のNext.jsの推奨設定でプロジェクトのひな形が自動的に作成される。

次に、Convexのセットアップに移る。Convexライブラリをプロジェクトにインストールするため、「npm install convex」を実行する。その後、「npx convex dev」コマンドを実行すると、Convexの環境が設定される。この際、アカウントのログインや新規作成が求められるので、指示に従って作業を進める。このステップが完了すると、プロジェクトのルートディレクトリに「convex/」というフォルダが作成され、その中に「_generated/」というフォルダが自動的に生成される。この「_generated/」フォルダには、Convexのバックエンド関数をフロントエンドから呼び出すためのコードが自動的に生成されるため、非常に重要なフォルダとなる。

Convexは従来のデータベースとは異なるアプローチをとっており、最初は戸惑うかもしれないが、基本的な概念を理解すれば非常に直感的で強力なツールであることがわかる。Convexでのデータ管理の第一歩は「スキーマの作成」だ。これは、データベースにどのような種類のデータを、どのような構造で保存するかを定義する作業である。プロジェクト内の「convex/schema.ts」ファイルに、Convexが提供する「defineSchema」と「defineTable」という関数を使って、例えば「users」テーブルや「tasks」テーブルといったデータの入れ物（テーブル）とその中身（フィールド）を定義する。「v」というオブジェクトを使って、フィールドが文字列（v.string()）なのか、数値（v.number()）なのか、真偽値（v.boolean()）なのかといった型安全な定義ができる。もし既存のデータがある場合は、「npx convex import --table tasks sampleData.jsonl」というコマンドを使って、外部ファイルからデータをインポートすることも可能だ。

Convexの核となる概念の一つが「ミューテーション」だ。これは、データベースに対するデータの作成、更新、削除といった操作を行うための関数群を指す。ミューテーションは、フロントエンド（ユーザーインターフェース）とデータベースの間でデータのやり取りを仲介する「橋渡し役」と考えると分かりやすい。例えば、ウェブページ上のフォームから入力されたデータをミューテーションが受け取り、それをデータベースに保存する。また、データベースに保存されているデータをミューテーションが取得し、それをウェブページに表示するといった使い方ができる。通常、フロントエンドのコンポーネント（例: business_profile.tsx）に対して、対応するミューテーションファイル（例: businessProfile.ts）を作成することが一般的である。

具体的なミューテーションとクエリ（データベースからデータを読み出す操作）の例を見てみよう。 まず、バックエンドの「convex/tasks.ts」ファイルに「createTask」というミューテーションと「getAllTasks」というクエリを定義する。「createTask」は新しいタスクを作成するミューテーションで、タスクのタイトルと説明を引数として受け取り、データベースの「tasks」テーブルに新しいエントリを挿入する。この時、完了状態（completed）や作成日時（createdAt）も一緒に保存される。「getAllTasks」はすべてのタスクを取得するクエリで、データベースの「tasks」テーブルからすべてのデータを取得して返す。 これらのバックエンドの関数を、フロントエンドのReactコンポーネントである「app/tasks/page.tsx」から利用する。「useMutation」フックを使って「createTask」を呼び出し、フォームからの入力データ（タイトルと説明）を渡してタスクを作成する。「useQuery」フックを使って「getAllTasks」を呼び出し、データベースから取得したタスクのリストをページ上に表示する。このように、Convexは自動的に生成される「api」オブジェクトを通じて、バックエンドの関数をフロントエンドから非常に簡単に利用できる仕組みを提供している。 このタスク管理の例におけるスキーマは、「convex/schema.ts」ファイルで「tasks」テーブルを定義し、タイトル（string）、説明（string）、完了状態（boolean）、作成日時（number）といったフィールドを持つことを示している。ここで重要なのは、すべてのミューテーションとクエリのファイルは「convex/」フォルダ内に配置する必要があるという点だ。そうすることで、Convexがこれらの関数を認識し、「_generated/」フォルダに適切なコードを生成してくれる。

アプリケーションがConvexと通信できるようにするためには、「ConvexClientProvider.tsx」というファイルを作成し、アプリケーション全体をこのプロバイダーでラップする必要がある。これは、Next.jsの「app/layout.tsx」ファイルで、メインのコンテンツ（children）を「<ConvexClientProvider>」で囲むことで実現する。この設定により、アプリケーション内のどのコンポーネントからでもConvexのデータにアクセスできるようになる。

開発中に遭遇しやすい一般的な問題とその解決策も覚えておくと良い。例えば、「npx convex dev」コマンドは、ファイルを作成するたびに頻繁に実行するのではなく、いくつかのページや機能を作成してからまとめて実行すると、エラーが少なく、管理しやすくなることが多い。また、稀に「_generated/」フォルダが正しく更新されない場合がある。その際は、「rm -r _generated/」コマンドでこのフォルダを一度削除してから、「npx convex dev」を再度実行すると解決することが多い。このフォルダはConvexによって自動的に再生成されるため、安全に削除できる。TypeScriptのエラーなど、原因が分かりにくい問題が発生した場合は、Convexダッシュボードのログを確認すると、より詳細なエラー情報が得られることがある。さらに、Convexダッシュボードには、定義した関数を直接テストできる便利な機能も備わっているため、デバッグ時に活用すると良いだろう。

アプリケーションをデプロイする際には、Convexの設定画面に表示される「Deployment URL」と「HTTP Actions URL」を、Vercelなどのデプロイサービス側の環境変数として設定する必要がある。これにより、デプロイされたアプリケーションが正しくConvexのバックエンドと通信できるようになる。

筆者はこれまでデータベースを苦手としていたが、Convexを使ってみて、その直感的なシンプルさに感銘を受けたという。Convexの学習曲線は存在するが、基本を理解すれば非常に楽しく開発を進められる。このGritPath OSプロジェクトは、企業が事業の青写真を作成し、レベルアップするのを支援するプラットフォームであり、無事にProduct Huntにも公開された。今後の記事では、Clerk認証やデプロイの詳細についてさらに深く掘り下げていく予定だ。

本記事は初心者向けの内容となっているため、Convexの経験者からのさらなる知見も歓迎している。 新しいデータベースへの移行で直面した課題があれば、ぜひ共有してほしい。