メインコンテンツへスキップ
このガイドはNotCMS 0.5.0以降を使います。Node.js 22以降と、サーバー側でTypeScriptを 実行できるプロジェクトが必要です。SDKの開発作業用ツールには別のNode要件がありますが、 SDK利用時の対応ランタイムとは異なります。

1. データベースを接続する

ダッシュボードでワークスペースを作成または選択し、 Notionを接続して、利用するデータベースへのアクセスを許可します。 データベースを登録し、初回同期の完了を待ってください。 未同期のデータベースからは、以下で使うコンテンツやスキーマを取得できません。

2. インストールして初期化する

アプリのルートディレクトリで実行します。
init は notcms.config.json を作成し、認証情報がなければブラウザログインを案内して、 最初のスキーマを取得します。登録したデータベースを含むワークスペースを選んでください。 既定では認証情報を .env.local、スキーマを src/notcms/schema.ts に保存します。 最後に実際のデータベース名を使ったクエリが表示されます。保存先の変更は init を参照してください。 .env.local はGitに含めないでください。CLIはこのファイルを読みますが、アプリもサーバー側で 読み込む必要があります。Next.jsは .env.local を読み込みます。通常のNode.jsアプリでは、 node --env-file=.env.local で起動するか、dotenv.config({ path: ".env.local" }) のあとで 生成クライアントを動的な import() で読み込んでください。静的な import は dotenv.config() より先に 実行されるため、環境変数のないままクライアントが作られます。 NOTCMS_SECRET_KEY をブラウザ向けの環境変数で公開しないでください。 詳しくはクライアントの初期化を参照してください。

ブラウザログインを使わない場合

ブラウザログインは NOTCMS_SECRET_KEY と NOTCMS_WORKSPACE_ID をenvファイルに書き込むだけです。 すべてのコマンドはこの2つの変数を読むため、ログインは省略できます。 ダッシュボードの ワークスペースのシークレット でシークレットを作成し、 2つの変数を環境変数かenvファイルに設定してください。設定済みなら init も pull もブラウザを開きません。 CI、コンテナ、ブラウザログインを使えないリモート環境やエージェントのセッション、追加のGitワークツリーではこの方法を使います。
生成したスキーマはコミットし、ビルド時にpullしなくて済むようにします。CIでは変数をシークレットとして渡し、 npx notcms pull --check を実行してください。詳しくはCIでのスキーマ確認を参照してください。

3. 一覧を取得する

サーバー側でクエリを実行します。blog とプロパティ名は、生成されたスキーマに合わせて置き換えてください。 以下は published というチェックボックスがある場合の例です。
このimportは、既定のスキーマ保存先を使い、src/example.ts から実行する場合のパスです。 SDKはエラータプルを返すため、データを読む前に error を確認します。 空の配列は取得に成功したものの、同期済みページに条件と一致するものがないことを表します。

4. Markdown本文を取得する

一覧のページIDを指定して本文を取得します。
get はIDで取得するため、一覧の公開条件を適用しません。 公開サイトの個別ページを描画する前に、公開条件を再確認してください。 その実装には検証済みのコンテンツレシピを利用できます。 URLにslugを使う場合は getFirst を参照してください。

サイトを最新に保つ

Notionの本文を編集したら、同期を待ち、必要に応じてサイトのキャッシュ更新や再ビルドを行います。 データベースのプロパティを変更した場合は、さらに npx notcms pull とアプリの型検査を実行します。 pull は同期済みのスキーマを取得するコマンドで、コンテンツの同期は開始しません。 次は Next.js、Astro、 CIでのスキーマ確認へ進めます。 古い環境からの更新は移行ガイドを参照してください。