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

アプリ

Squid を Next.js と一緒に使うと、アプリケーションのサーバー側とクライアント側の両方で Squid クライアントにアクセスできます。サーバーでは、初期ペイロードの一部としてデータをクエリできます。クライアントでは、クエリ、ミューテーション（mutations）、およびリアルタイムのデータ更新をストリーミングで受け取ることができます。

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>
  );
}

ユーザーをクエリする​

次に、ユーザーのリストを表示する新しいコンポーネントを作成します。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 は、標準で built-in database（組み込みデータベース）を提供します。この例では、Users の client component 内で useQuery フックを使い、データベースの users コレクションに対するクエリを実行します。このフックはクエリと boolean を受け取り、その boolean はテーブルへのライブ更新にサブスクライブしたいかどうかを示します。query().dereference() を使うと、クエリの生データ（raw data）を返します。

Web アプリでは “Users” の見出しが表示されますが、ユーザーがいません！ まだコレクションにユーザーを挿入していないためです。

Note

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

ユーザーを挿入する​

データベースにユーザーを挿入する関数をトリガーする button component を追加します。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 のユーザーが挿入されます。データベースクエリはライブ更新にサブスクライブしているため、ボタンをクリックするとすぐにユーザー ID がユーザー一覧に表示されます。collection.doc().insert(...) を実行すると、ユーザーデータがアプリケーションの built-in database に永続化されるため、ページをリロードしてもユーザー一覧は保持されます。

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

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

app/page.tsx で Squid クエリを直接実行して初期ユーザーデータを取得し、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 にアクセスできないためです。代わりに @squidcloud/client パッケージを使って別のインスタンスを作成する必要があります。このパッケージは Squid React SDK をインストールすると自動的にインストールされます。コードの重複を減らすため、Squid options を取得する共有ユーティリティの作成をおすすめします。

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 フックを更新して初期値を受け取るようにします。

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

これらの変更により、ページをリロードしても Loading… インジケーターは表示されなくなります。代わりに、ページロードと同時にユーザー一覧が表示されます。

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

ここまでで、React Server Component でデータをクエリし、それを client component に渡して initial query value として使う方法を学びました。しかし、クエリのロジックが 2 か所（Home React Server Component と Users client component）に存在していることに気づくでしょう。これはメンテナンスが難しく、片方だけクエリを変更してもう片方の更新を忘れるといった問題が起きやすくなります。

重複を避けるために、Squid React SDK は withServerQuery 関数を公開しています。この hook はサーバー側でのデータクエリと、それを client component に渡す処理を担います。

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

  1. クエリデータを受け取る client component
  2. 実行するクエリ
  3. クエリ更新にサブスクライブするかどうか

この関数は、その後 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 フックをコンポーネントから削除します。データは withServerQuery によるラップから供給されるようになります。
  2. users prop を data にリネームします。withServerQuery はラップした client component に data prop を渡します。
  3. prop type を 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… インジケーターもデータのチラつきもなく、すべてのユーザーが表示されるようになります。さらに Insert をクリックすると、ユーザー一覧は引き続き動的に更新されます。

Note

クエリへのサブスクライブがどのように動作するか試したい場合は、withServerQuery 関数内の true を false に変えてみてください。この場合でもロード時にユーザーデータは表示されますが、ユーザーを挿入してもユーザー一覧がライブ更新 されません（ページをリロードするとユーザーが存在します）。これは、client component で変更にサブスクライブしていないためであり、実際 Squid クエリはクライアントではまったく実行されません！

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

サーバーでデータを挿入する​

サーバーでデータをクエリするだけでなく、Squid を router handlers や server actions の中でも使用できます。サーバーからユーザーを挿入してみましょう。

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 関数と非常によく似ていることに気づくでしょう。どちらも built-in database にユーザーを作成するという目的は同じですが、今度はクライアントではなくサーバーで実行されます。

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

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

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

これで “Insert” ボタンをクリックすると、サーバーからユーザーが挿入されます！

Optimistic updates​

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

クライアント側実装の insertUser では、insert はクライアント上で直接行われます。この場合 Squid は楽観的に insert を実行するため、insert リクエストがまだ処理中（in flight）であっても新しいユーザーが即座に表示されます。そして、何らかの理由で insert が失敗した場合、Squid は楽観的 insert をロールバックします。

Tip

サーバーから挿入する場合、optimistic updates の利点は失われます。一般に、API routes の中で Squid を使って挿入することもできますが、ユーザー体験としてはクライアントから直接 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 は form の submit によって import して呼び出すことができます。作成した 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 をサポートしません。