NewtとAstroを利用してブログを作成する

このチュートリアルでは、Newtと Astro を利用して、ブログを作成する手順を紹介します。
具体的には、Newtで管理しているコンテンツの一覧ページと詳細ページを作る手順を紹介します。

記事内で使用している主なソフトウェアのバージョン

  • Astro(astro): 2.0.1
  • newt-client-js(newt-client-js): 3.2.4

概要

Astroでプロジェクトを作成し、Newtのコンテンツ情報を取得できるようにします。
コンテンツの一覧ページ(パス: /)と詳細ページ(パス: /articles/:slug 。slugがarticle-1の場合は /articles/article-1)を作成し、ローカル環境で表示を行うまでを説明します。
また、ここではビルド時にHTMLを生成する、静的生成(Static Generation)の方法を紹介します。

1. Astroのセットアップ

はじめに、Astroのセットアップを行います。create-astro を利用することで、簡単にAstroのプロジェクトを作成できます。
以下のどれかのコマンドを入力します。

npm create astro@latest
# or
pnpm create astro@latest
# or
yarn create astro

コマンドを入力すると、以下の質問を聞かれるので、お好きな設定を選びましょう。

  • どこにプロジェクトを作成するか(ここでは ./astro-blog としました)
  • プロジェクトのセットアップをどうするか(ここでは a few best practices (recommended) を選択)
  • dependenciesをインストールするか(ここでは yes を選択)
  • 新しいgitリポジトリを初期化するか?(ここでは yes を選択)
  • TypeScriptの設定をどうするか(ここでは Strict を選択)

yarnを利用した場合、以下のように表示されます。

$  yarn create astro
yarn create v1.22.18
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
success Installed "create-astro@2.0.1" with binaries:
      - create-astro

╭─────╮  Houston:
│ ◠ ◡ ◠  I'll be your assistant today.
╰─────╯

 astro   v2.0.1 Launch sequence initiated.

✔ Where would you like to create your new project? … ./astro-blog
✔ How would you like to setup your new project? › a few best practices (recommended)
✔ Template copied!
✔ Would you like to install yarn dependencies? (recommended) … yes
✔ Packages installed!
✔ Would you like to initialize a new git repository? (optional) … yes
✔ Git repository created!
✔ How would you like to setup TypeScript? › Strict
✔ TypeScript settings applied!

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./astro2-blog
         Run yarn dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat

╭─────╮  Houston:
│ ◠ ◡ ◠  Good luck out there, astronaut!
╰─────╯
✨  Done in 45.03s.

作成したプロジェクトに移動して、開発サーバーを立ち上げます。

$ cd astro-blog
$ yarn dev

http://localhost:3000/ にアクセスして、以下のような画面が表示されることを確認します。
astro-blog1.png

2. Newtのセットアップ

次にNewtにコンテンツとAPIトークンを用意し、コンテンツの取得を行うための準備を行います。

2-1. Appを追加する

「Appを追加」をクリックして「テンプレートから追加」を選択します。

Appを追加する

表示されるテンプレートの中から「Blog」を選択して、「このテンプレートを追加」をクリックします。
Appテンプレート

テンプレートが追加されると、「投稿データ」「カテゴリデータ」「著者データ」が追加されます。

quick-start03.jpg

2-2. スペースUID・App UID・モデルUIDを確認する

スペースUIDは「スペース設定」から確認できます。

quick-start0402.jpgquick-start0503.jpg

上記の例だと、スペースUIDは sample-for-docs となります。
この値は3-1で環境変数として定義します。

また「Blog」テンプレートを追加した場合、App UIDは blog、「投稿データ」モデルUIDは article となります。
これらの値は、4-2や5-1で投稿情報を取得する際に利用します。

2-3. Newt CDN API Tokenを作成する

続いて、APIリクエストに必要なトークンを発行します。
スペース設定 > APIキー のページからNewt CDN API Tokenを作成します。

quick-start06.jpg

名前と取得対象を決めて「作成」を押します。

quick-start07.jpg

ここで作成したトークンの値は3-1で環境変数として定義します。

3. リクエストの準備

Newtの SDK を利用することで、NewtのAPIをより簡単に利用できます。
ここではSDKを利用して、NewtのAPIクライアントを作成します。

3-1. 環境変数の設定

Astroの環境変数は、プロジェクトディレクトリの .env ファイルから読み込めます。詳細はAstroの 環境変数 のドキュメントをご確認ください。

ここでは、.env ファイルを作成し、2-2で確認したスペースUID、2-3で作成したトークンの値を定義します。以下を、実際の値で置き換えて定義してください。

NEWT_SPACE_UID=sample-for-docs
NEWT_CDN_API_TOKEN=xxxxxxxxxxxxxxx

上記のように定義しておくと、import.meta.env.NEWT_SPACE_UIDimport.meta.env.NEWT_CDN_API_TOKEN として利用できるようになります。

また、src/env.d.tsImportMetaEnv を以下のように設定することで、環境変数の自動補完が効くようになります。

/// <reference types="astro/client" />

+ interface ImportMetaEnv {
+   readonly NEWT_SPACE_UID: string
+   readonly NEWT_CDN_API_TOKEN: string
+ }

3-2. newt-client-jsのインストール

次に newt-client-js をインストールします。

npm install newt-client-js
# or
yarn add newt-client-js

3-3. APIクライアントの作成

CDN APIを利用するためのクライアントを作成します。
spaceUidtoken のところには3-1で設定した環境変数を入力します。
ここではCDN APIを利用するので、apiType には cdn を指定しましょう。

// src/lib/newt.ts

import { createClient } from 'newt-client-js'

export const newtClient = createClient({
  spaceUid: import.meta.env.NEWT_SPACE_UID,
  token: import.meta.env.NEWT_CDN_API_TOKEN,
  apiType: 'cdn',
})

これで、NewtにAPIリクエストを送るための準備ができました。

4. 一覧ページの作成

4-1. 投稿の型を定義する

はじめに、投稿の型 Article を定義しておきます。
このチュートリアルでは、titleslugbody のみを使うため、以下のように定義しておきます。

// src/lib/newt.ts

import { createClient } from 'newt-client-js'

+ export interface Article {
+   title: string
+   slug: string
+   body: string
+ }

export const newtClient = createClient({
  spaceUid: import.meta.env.NEWT_SPACE_UID,
  token: import.meta.env.NEWT_CDN_API_TOKEN,
  apiType: 'cdn',
})

4-2. 投稿一覧の取得メソッドを作成する

Astroはファイルベースルーティングを採用しており、src/pages ディレクトリの配下にファイルを作成すると、自動的にルートとして利用できるようになります。
例えば、以下のようにルーティングされます。

  • src/pages/blog/index.astro/blog
  • src/pages/blog/first-post.astro/blog/first-post

※ ルーティングの詳細については、Astroの 静的ルーティング のドキュメントをご確認ください。

ここではトップページ(パス: /)で投稿一覧を表示したいので、src/pages/index.astro のファイルを修正します。

投稿一覧を取得するために、SDKが提供している getContents メソッドを利用します。getContentsはNewtのコンテンツ一覧を取得するためのメソッドです。getContentsのパラメータに Article の型を渡すことで、返却される items の型として Article[] が指定されます。
また、selectパラメータを利用して、取得するフィールドを titleslugbody のみに制限します。

// src/pages/index.astro

---
import Layout from '../layouts/Layout.astro'
import { newtClient } from '../lib/newt'
import type { Article } from '../lib/newt'

const { items: articles } = await newtClient.getContents<Article>({
  appUid: 'blog',
  modelUid: 'article',
  query: {
    select: ['title', 'slug', 'body'],
  },
})
---

<Layout title="Articles">
  <main></main>
</Layout>

4-3. 投稿一覧を表示する

次に、投稿一覧を表示します。src/pages/index.astro は以下のようになります。

// src/pages/index.astro

---
import Layout from '../layouts/Layout.astro'
import { newtClient } from '../lib/newt'
import type { Article } from '../lib/newt'

const { items: articles } = await newtClient.getContents<Article>({
  appUid: 'blog',
  modelUid: 'article',
  query: {
    select: ['title', 'slug', 'body'],
  },
})
---

<Layout title="Articles">
  <main>
    <ul>
      {
        articles.map((article) => {
          return (
            <li>
              <a href={`/articles/${article.slug}`}>{article.title}</a>
            </li>
          )
        })
      }
    </ul>
  </main>
</Layout>

ここでは詳細ページへのリンクとして、HTML標準の <a> 要素を利用しています。
詳細については、Astroの ページ間のリンク をご確認ください。

http://localhost:3000/ にアクセスして、以下のように投稿一覧が表示されれば成功です。

astro-blog2.png

5. 詳細ページの作成

5-1. 動的ルーティングを設定する

Astroで 動的ルーティング を設定するためには、以下の2つが必要です。

  1. src/pages/blog/[slug].astrosrc/pages/[username]/settings.astro のように、角括弧を使って動的なパラメータを識別すること
  2. getStaticPaths() 関数をエクスポートして、Astroでプリレンダリングされるパスを正確に指定すること

まず、ここでは /articles/:slug/articles/article-1 など)のパスで投稿の詳細を表示したいので、src/pages/articles/[slug].astro のファイルを作成します。

次に getStaticPaths() 関数を作成します。この関数の params キーによって、どのパスがプリレンダリングされるか決まります。
ここでは全投稿のスラッグを定義するため、以下のように params を指定します。
投稿一覧を取得する部分は4-2と同じです。

// src/pages/articles/[slug].astro

---
import Layout from '../../layouts/Layout.astro'
import { newtClient } from '../../lib/newt'
import type { Article } from '../../lib/newt'

export const getStaticPaths = async () => {
  const { items: articles } = await newtClient.getContents<Article>({
    appUid: 'blog',
    modelUid: 'article',
    query: {
      select: ['title', 'slug', 'body'],
    },
  })
  return articles.map((article) => ({
    params: { slug: article.slug },
  }))
}
---

<Layout title="Article">
  <main></main>
</Layout>

5-2. 投稿詳細を表示する

次に、投稿詳細を表示します。

ここでは getStaticPathsprops を利用して、投稿データを渡しています。
src/pages/articles/[slug].astro は以下のようになります。

// src/pages/articles/[slug].astro

---
import Layout from '../../layouts/Layout.astro'
import { newtClient } from '../../lib/newt'
import type { Article } from '../../lib/newt'

export const getStaticPaths = async () => {
  const { items: articles } = await newtClient.getContents<Article>({
    appUid: 'blog',
    modelUid: 'article',
    query: {
      select: ['title', 'slug', 'body'],
    },
  })
  return articles.map((article) => ({
    params: { slug: article.slug },
    props: { article },
  }))
}

const { article } = Astro.props
---

<Layout title="Article">
  <main>
    <h2>{article.title}</h2>
    <article set:html={article.body} />
  </main>
</Layout>

※ bodyの表示で利用されている set:html はXSSの危険性があるため、利用には注意が必要です。ここでは、Newtで管理している投稿情報を表示するものであり、不特定多数のユーザーが入力できるものを表示するわけではないため、安全なものとして利用しています。

これで、投稿詳細についての設定も完了です。
http://localhost:3000/articles/article-3 にアクセスして、以下のように投稿詳細が表示されれば成功です。

astro-blog3.png

次のステップ

このチュートリアルを行うことで、Astroのプロジェクトを作成し、開発環境でコンテンツの取得・表示を行う方法を学習しました。
更に深く学習したい方は、以下のチュートリアルもおすすめです。

ホスティングを行いたい方

その他にも様々なチュートリアルを用意しているので、ぜひ チュートリアル のページもご確認ください。

Newt Made in Newt