メインコンテンツまでスキップ

Next.js と Squid

Squid は特定の思想に縛られない（unopinionated）プラットフォームとして、お好きなフロントエンド／フルスタックフレームワークと併用できます。Next.js を使っている場合は、プロジェクトに Squid を追加することで、データソースへの接続を効率化し、追加のセキュリティを提供し、リアルタイムのデータ更新をサポートするなど、さまざまなことが可能になります。さらに Next.js 開発者をよりよくサポートするために、Squid と Next.js を組み合わせた開発をシームレスにするいくつかの hooks も追加しました。

TL;DR​

このチュートリアルでは、Squid を Next.js アプリに統合する方法を学びます。内容は次のとおりです。

  • クライアントに対してリアルタイムでクエリと更新のストリーミングを行う
  • ページロード時に Next.js サーバーからデータをクエリする
  • クライアントとサーバーの両方からデータを変更（mutate）する

このドキュメントは、Pages Router を使っているか App Router を使っているかによって少し異なるため、下の正しいオプションを選択してください。

新しい Next.js アプリを作成する​

  1. next-tutorial-project というルートプロジェクトディレクトリを作成します。
mkdir next-tutorial-project

next-tutorial-project ディレクトリに移動し、次のいずれかのコマンドを実行して Next.js アプリを作成します。

App Router の場合:

cd next-tutorial-project
npx create-next-app@latest next-tutorial --ts --tailwind --eslint --app --no-src-dir

Pages Router の場合:

cd next-tutorial-project
npx create-next-app@latest next-tutorial --ts --tailwind --eslint --no-src-dir

このプロジェクトについて、いくつか注意点があります。

  • このプロジェクトは TypeScript を使用していますが、ご自身のプロジェクトでは JavaScript を使用しても構いません。
  • Pages Router と App Router のどちらも Squid と統合できます。このチュートリアルでは好みの方法を選んでください。
  • このプロジェクトは Tailwind CSS でスタイリングされています。

プロジェクトを作成したら、next-tutorial ディレクトリに移動して Squid React SDK をインストールします。Squid React SDK は、Squid を React および Next.js プロジェクトに統合するための hooks とユーティリティを提供します。

cd next-tutorial
npm install @squidcloud/react

Squid backend を作成する​

  1. Squid Console に移動し、next-tutorial という名前の新しい application を作成します。
Note

Squid には 2 つの target environment があります。開発用の dev と、本番用の prod です。このチュートリアルでは開発向けに設計された dev environment を使用します。アプリケーションが動作するように、プロジェクト全体を通して dev environment を使用していることを確認してください。詳しくは Squid の environments を参照してください。

  1. Squid Console で application の overview ページに移動し、Backend project セクションまでスクロールします。Initialize backend をクリックし、初期化コマンドをコピーします。

  2. ルートプロジェクトディレクトリに移動します。

cd ..
  1. Console からコピーしたコマンドを使って backend を初期化します。コマンドの形式は次のとおりです。
squid init next-tutorial-backend --appId [YOUR_APP_ID] --apiKey [YOUR_API_KEY] --environmentId dev --squidDeveloperId [YOUR_SQUID_DEVELOPER_ID] --region [YOUR_REGION (likely us-east-1.aws)]

プロジェクトを実行する​

Squid プロジェクトをローカルで実行するには、クライアントアプリと backend の Squid プロジェクトの両方をローカルで実行する必要があります。

  1. next-tutorial-backend ディレクトリに移動し、squid start を使って backend を起動します。
cd next-tutorial-backend
squid start
  1. 新しいターミナルウィンドウを開き、next-tutorial ディレクトリに移動します。その後、アプリを実行します。
cd next-tutorial
npm run dev

これで Next.js アプリプロジェクトは http://localhost:PORT で稼働しています。PORT はターミナルに表示されます。まだページに表示する内容を編集していないため、表示されるのは Next.js のスタータープロジェクトです。

Router​

ここから先は、Next.js を App Router で使っているか Pages Router で使っているかによって、このチュートリアルの内容が分岐します。Next.js プロジェクト作成時に選択したオプションを選んでください。


アプリ

Next.js で Squid を使用する場合、アプリケーションのサーバー側とクライアント側の両方で Squid client にアクセスできます。サーバーでは、初期ペイロードの一部としてデータをクエリできます。クライアントでは、query、mutation を実行したり、リアルタイムのデータ更新をストリーミングで受け取ったりできます。

App Router では、use client と use server ディレクティブを使って、クライアントでレンダリングされるコンポーネントとサーバーでレンダリングされるコンポーネントを区別できます。React Server Components (RSCs) は、レンダリング前に（データのクエリのような）非同期処理を実行できる点が特徴です。このチュートリアルでは、まずクライアントで Squid を使い始め、その後 React Server Components を使う流れに進みます。

まず app/layout.tsx で、children を SquidContextProvider でラップします。プレースホルダーを Squid の設定オプションに置き換えてください。これらの値は Squid Console または .env ファイルで確認できます。.env ファイルは Squid backend の作成 時に自動生成され、backend ディレクトリ内にあります。

app/layout.tsx
import './globals.css';
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import { SquidContextProvider } from '@squidcloud/react';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <SquidContextProvider
          options={{
            appId: 'YOUR_APP_ID',
            region: 'YOUR_REGION',
            environmentId: 'dev',
            squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
          }}
        >
          {children}
        </SquidContextProvider>
      </body>
    </html>
  );
}

users をクエリする​

次に、ユーザー一覧を表示する新しいコンポーネントを作成します。app ディレクトリ配下に新しい components ディレクトリと、users.tsx という新しいファイルを作成してください。新しいファイルに以下のコードを追加します。

app/components/users.tsx
'use client';

import { useCollection, useQuery } from '@squidcloud/react';

type User = {
  id: string;
};

export default function Users() {
  const collection = useCollection<User>('users');

  const { loading, data, error } = useQuery(collection.query().dereference());

  if (loading) {
    return <div className="flex flex-col items-center justify-center min-h-screen">Loading...</div>;
  }

  if (error) {
    return <div className="flex flex-col items-center justify-center min-h-screen">{error.message}</div>;
  }

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <span>Users</span>
      <ul>
        {data.map((user) => (
          <li key={user.id}>{user.id}</li>
        ))}
      </ul>
    </div>
  );
}

Users コンポーネントをレンダリングするために、app/page.tsx のコードをすべて次の内容に置き換えます。

app/page.tsx
import Users from '@/components/users';

export default function Home() {
  return <Users />;
}

Squid は標準で組み込み database を提供します。この例では、Users クライアントコンポーネント内で useQuery hook を使い、database の users collection に対するクエリを実行します。hook はクエリと boolean を受け取り、その boolean はテーブルのライブ更新に subscribe するかどうかを示します。query().dereference() を使うと、クエリの raw data が返ります。

Web アプリでは “Users” の見出しが表示されますが、ユーザーがいません！ まだ collection にユーザーを insert していないためです。

Note

“Loading…” や error message が表示される場合は、Squid backend を起動したか確認してください。tutorial-backend に移動して squid start を実行します。Running the project を参照してください。

ユーザーを insert する​

database にユーザーを insert する関数をトリガーする button コンポーネントを追加します。components/users.tsx に以下を追加してください。

components/users.tsx
import { useCollection, useQuery } from "@squidcloud/react";

...

export default function Users() {
  ...

  const insertUser = async () => {
    await collection.doc().insert({
      id: crypto.randomUUID(),
    });
  }
  ...

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <button onClick={insertUser}>Insert</button>
      <span>Users</span>
      <ul>
        {data.map((user) => (
          <li key={user.id}>{user.id}</li>
        ))}
      </ul>
    </div>
  );

Web アプリに Insert ボタンが表示されます。ボタンをクリックするとランダムな ID を持つユーザーが insert されます。database クエリはライブ更新に subscribe されているため、ボタンをクリックした直後にユーザー ID がユーザー一覧に表示されます。collection.doc().insert(...) を実行すると、ユーザーデータがアプリケーションの組み込み database に永続化されるため、ページをリフレッシュしてもユーザー一覧は保持されます。

サーバーでクエリを実行する​

ページをリフレッシュすると、ユーザー一覧が表示される前に Loading…* のインジケーターが短時間表示されます。これは Users コンポーネントがクライアントコンポーネントであり、クライアント側で users をクエリするのに少し時間がかかるためです。Next.js App Router では、このクエリを React Server Component 内で実行し、ページロード時にそのデータをサーバーからクライアントへ渡せます。

app/page.tsx で Squid query を直接実行して初期 user data を取得し、その users のリストを Users コンポーネントの初期レンダリングに渡します。

app/page.tsx
import Users from '@/components/users';
import { Squid } from '@squidcloud/client';

type User = {
  id: string;
};

export default async function Home() {
  const squid = Squid.getInstance({
    appId: 'YOUR_APP_ID',
    region: 'YOUR_REGION',
    environmentId: 'dev',
    squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
  });

  const users = await squid.collection<User>('users').query().dereference().snapshot();

  return <Users users={users} />;
}
Note

アプリの初期設定では、クライアント側で SquidContextProvider により Squid を初期化しました。この Squid インスタンスは Home ページ内からはアクセスできません。React Server Components は React Context にアクセスできないためです。代わりに、Squid React SDK をインストールすると自動的にインストールされる @squidcloud/client package を使って、別のインスタンスを作成する必要があります。コードの重複を減らすために、Squid options を取得する共有 utility を作ることを推奨します。

utils というフォルダを作成し、squid.ts というファイルを追加します。新しいファイルに以下のコードを追加してください。

utils/squid.ts
import { SquidOptions } from '@squidcloud/client';

export function getOptions(): SquidOptions {
  return {
    appId: 'YOUR_APP_ID',
    region: 'YOUR_REGION',
    environmentId: 'dev',
    squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
  };
}

これで options={...} はどこでも options={getOptions()} に置き換えられます。

app/layout.tsx で getOptions 関数を import し、SquidContextProvider の options として渡します。

app/layout.tsx
import { getOptions } from "@/utils/squid";

...

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <SquidContextProvider options={getOptions()}>
          {children}
        </SquidContextProvider>
      </body>
    </html>
  );
}

サーバーでクエリした users にアクセスできるようになったので、Users コンポーネントの useQuery hook を更新して初期値を受け取れるようにします。

app/components/users.tsx
...

export default function Users({ users }: { user: Array<User> }) {
  ...

  const { loading, data, error } = useQuery(
    collection.query().dereference(),
    { initialData: users }
  );

  ...

  if (loading && !data.length) {
    return (
      <div className="flex flex-col items-center justify-center min-h-screen">
        Loading...
      </div>
    );
  }

  ...
}

このコードブロックでは 2 つの変更を行っています。

  1. useQuery hook に初期データとして users のリストを渡します。これにより hook から返される初期 data が空配列ではなくユーザー一覧になります。
  2. Loading… の条件を「データが存在するか」を確認するように更新します。デフォルトでは、useQuery に初期値を渡しても、クライアントでデータのクエリが成功するまでは loading は true のままです。data の存在をチェックすることで、クライアント側のクエリがまだ loading 中でも、サーバーからのユーザー一覧をレンダリングできます。

これらの変更により、ページをリフレッシュしても Loading… インジケーターは表示されなくなります。代わりに、ページロード直後からユーザー一覧が表示されます。

withServerQuery を使って重複を最小化する​

ここまでで、React Server Component でデータをクエリし、それをクライアントコンポーネントに渡して初期クエリ値として使う方法を学びました。しかし、クエリのロジックが 2 箇所（Home の React Server Component と Users のクライアントコンポーネント）に存在していることに気づくでしょう。これは、片方のクエリを変更してもう片方を更新し忘れるなど、保守が難しくなる場合があります。

重複を避けるために、Squid React SDK には withServerQuery 関数が用意されています。この hook は、サーバー側でデータをクエリし、それをクライアントコンポーネントへ渡す処理を担います。

Home ページを更新して新しい withServerQuery 関数を使用します。この関数は 3 つの引数を取ります。

  1. クエリデータを受け取るクライアントコンポーネント
  2. 実行するクエリ
  3. クエリ更新に subscribe するかどうか

この関数は、Users コンポーネントをレンダリングするために使える Higher Order Component を生成します。app/page.tsx を更新して新しい関数を含めてください。

import Users from '@/components/users';
import { Squid } from '@squidcloud/client';
import { getOptions } from '@/utils/squid';
import { withServerQuery } from '@squidcloud/react';

type User = {
  id: string;
};

export default async function Home() {
  const squid = Squid.getInstance(getOptions());

  const UsersWithQuery = withServerQuery(
    Users,
    squid.collection<User>('users').query().dereference(),
    true
  );
  return <UsersWithQuery />;
}

この新しい関数に合わせて、Users コンポーネント側にもいくつか変更が必要です。

  1. コンポーネントから useQuery hook を削除します。データは withServerQuery のラッパー関数から供給されるようになります。
  2. users prop を data にリネームします。withServerQuery はラップしたクライアントコンポーネントに data prop を渡します。
  3. prop の型を WithQueryProps<User> に更新します。これは実質的に { data: Array<User> } を表すラッパーです。
  4. if (loading) {...} と if (error) {...} の条件分岐を削除します。コンポーネントがレンダリングされる前にデータがロードされるため、不要になります。

その結果、新しい components/users.tsx は次のようになります。

components/users.tsx
'use client';

import { useCollection, WithQueryProps } from '@squidcloud/react';

type User = {
  id: string;
};

export default function Users({ data }: WithQueryProps<User>) {
  const collection = useCollection<User>('users');

  const insertUser = async () => {
    await collection.doc().insert({
      id: crypto.randomUUID(),
    });
  };

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <button onClick={insertUser}>Insert</button>
      <span>Users</span>
      <ul>
        {data.map((user) => (
          <li key={user.id}>{user.id}</li>
        ))}
      </ul>
    </div>
  );
}

Next.js アプリをリロードしてください。Loading… インジケーターもデータのちらつきもなく、すべての users が表示されます。さらに Insert をクリックすると、ユーザー一覧が引き続き動的に更新されます。

Note

クエリの subscribe の動作を試したい場合は、withServerQuery 関数内の true を false に変更してみてください。この場合でもロード時にはユーザーデータが表示されますが、ユーザーを insert してもユーザー一覧はライブ更新されません（ページをリロードするとユーザーが表示されます）。これは、クライアントコンポーネント内で変更に subscribe しなくなるためであり、実際 Squid query はクライアントではまったく実行されなくなります。

変更に subscribe しない場合、実質的にサーバー側だけで Squid を使っていることになります。これは完全に有効なユースケースで、特にリアルタイムのデータ更新が不要な場合に適しています。

サーバーでデータを insert する​

サーバーでのクエリに加えて、router handlers や server actions 内でも Squid を使用できます。サーバーからユーザーを insert してみましょう。

Route handlers​

app/api/insert/route.ts 配下に新しい router handler を作成し、この route を次のコードに置き換えます。

app/api/insert/route.ts
import { getOptions } from '@/utils/squid';
import { Squid } from '@squidcloud/client';
import { NextResponse } from 'next/server';

type User = {
  id: string;
};

export async function POST() {
  const squid = Squid.getInstance(getOptions());
  const user = {
    id: crypto.randomUUID(),
  };
  await squid.collection<User>('users').doc().insert(user);
  return NextResponse.json(user);
}

このコードが Users コンポーネント内の insertUser 関数とよく似ていることに気づくでしょう。どちらも本質的には同じ目的（組み込み database にユーザーを作成する）を果たしますが、今度はクライアントではなくサーバーで実行されます。

クライアントからこの関数を呼び出すために、insertUser 関数を次のように更新します。

components/users.tsx
export default function Home(...) {
  ...

  const insertUser = async () => {
    await fetch("api/insert", { method: "POST" });
  };
  ...
}

“Insert” ボタンをクリックすると、サーバーからユーザーが insert されるようになります。

Optimistic updates​

ボタンをクリックしてから、insert されたユーザーがユーザー一覧に表示されるまでに少し遅延があることに気づくでしょう。これは、Squid がクライアントで optimistic updates を自動的に扱う仕組みによるものです。

insertUser のクライアント側実装では、insert がクライアントで直接行われます。この場合 Squid は optimistic に insert を行うため、insert リクエストがまだ処理中であっても新しいユーザーが即座に表示されます。そして、何らかの理由で insert が失敗した場合、Squid は optimistic insert を rollback します。

Tip

サーバーから insert する場合、optimistic updates の恩恵は失われます。一般に、Squid を API routes 内で使って insert することもできますが、ユーザー体験としてはクライアントから直接 insert と update を行う方が良いケースが多いです。

Server actions​

Route Handler に加えて、App Router では実験的な Server Actions をサポートしています。Server Actions を使うと、サーバー上で動的に実行できる関数をユーザーが書けます。

Server Actions を有効にするため、next.config.js を更新します。

next.config.js
module.exports = {
  experimental: {
    serverActions: true,
  },
};

actions という新しいフォルダを作成し、insert.tsx というファイルを追加して、次のコードを書きます。use server ディレクティブは、このファイルが Server Action を表すことを示します。

'use server';

import { Squid } from '@squidcloud/client';
import { getOptions } from '@/utils/squid';

type User = {
  id: string;
};

export default async function insertUser() {
  const squid = Squid.getInstance(getOptions());
  await squid.collection<User>('users').doc().insert({
    id: crypto.randomUUID(),
  });
}

クライアントでは、Server Actions は import して form を submit することで呼び出せます。先ほど作成した insertUser action を呼び出すには、Users コンポーネントを次のように更新します。

components/users.tsx
"use client";

import insertAction from '@/actions/insert';

...

export default function Users({ data }: WithQueryProps<User>) {
  ...

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
     <form action={insertAction}>
        <button type="submit">Insert</button>
      </form>
      <span>Users</span>
      <ul>
        {data.map((user) => (
          <li key={user.id}>{user.id}</li>
        ))}
      </ul>
    </div>
  );
}
Tip

Server Actions はサーバー側で実行されるため、optimistic updates はサポートされません。

以上です！​

Next.js と Squid の使い方を学習できました。両者を組み合わせることで、シンプルで効率的な Web 開発のアプローチが得られます。ぜひ取り組んで、楽しく開発してください！