App
Next.js で Squid を使用する場合、application の server side と client side の両方で Squid client に access できます。server では、initial payload の一部として data に query を実行できます。client では、query、mutation、real-time data update の stream を実行できます。
App Router では、use client と use server directive を使用して、client で render される component と server で render される component を区別できます。React Server Components（RSC）は、render 前に非同期処理（data の query など）を実行できる点で unique です。この tutorial では、client で Squid を使用することから始め、React Server Components での使用へ進みます。
最初に、app/layout.tsx で children を SquidContextProvider で wrap します。placeholder を Squid configuration option に置き換えます。これらの value は Squid Console または .env file にあります。.env file は Squid backend の作成時に自動生成され、backend directory にあります。
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>
);
}
User に Query を実行する
次に、user list を表示する新しい component を作成します。app directory の下に、新しい components directory と users.tsx という新しい file を作成します。新しい file に以下の code を追加します。
'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 component を render するには、app/page.tsx のすべての code を以下に置き換えます。
import Users from '@/components/users';
export default function Home() {
return <Users />;
}
Squid は out of the box で built-in database を提供します。この example では、Users client component の useQuery hook を使用して、database の users collection に query を実行します。hook は query と boolean を受け取ります。boolean は table の live update を subscribe するかを示します。query().dereference() を使用すると、query の raw data が返されます。
web app に “Users” heading が表示されますが、user はまだいません。collection に user を insert する必要があります。
“Loading…” または error message が表示される場合は、Squid backend を開始したことを確認してください。tutorial-backend に移動して squid start を実行します。Project の実行を参照してください。
User を Insert する
database に user を insert する function を trigger する button component を追加します。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 app に Insert button が表示されます。button をクリックすると random ID の user が insert されます。database query は live update を subscribe しているため、button をクリックするとすぐに user ID が user list に表示されます。collection.doc().insert(...) の実行により user data は application の built-in database に persist されるため、page を refresh しても user list は保持されます。
Server で Query を実行する
page を refresh すると、user list が表示される前に Loading…* indicator が一時的に表示されます。これは Users component が client component であり、client で user に query を実行するのに短い時間がかかるためです。Next.js App Router では、この query を React Server Component 内で実行し、page load 中に server から client に data を渡せます。
app/page.tsx で Squid query を直接実行して initial user data を取得し、users list を Users component の initial rendering に渡します。
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} />;
}
app を最初に setup した際、SquidContextProvider で client 上の Squid を初期化しました。React Server Component は React Context に access できないため、この Squid instance は Home page 内では access できません。代わりに、Squid React SDK の install 時に自動 install される @squidcloud/client package を使用して、別の instance を作成する必要があります。code の repetition を減らすため、Squid option を取得する shared utility の作成をおすすめします。
utils という folder を作成し、squid.ts という file を追加します。新しい file に以下の code を追加します。
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 function を import し、SquidContextProvider の options として渡します。
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>
);
}
server で query した users に access できたので、Users component の useQuery hook を update して initial value を受け取れるようにします。
...
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>
);
}
...
}
この code block は 2 つの change を行います。
userslist を initial data としてuseQueryhook に渡します。これにより hook が返す initialdataは empty array ではなく user list になります。- Loading… condition を update し、data が存在するかを check します。default では、
useQueryに initial value を渡した場合でも、client で data の query が成功するまでloadingvalue はtrueになります。dataの存在を check すると、client で query の loading 中にも server の user list を render できます。
これらの change により、page の refresh 時に Loading… indicator は表示されなくなります。代わりに page の load 時点で user list が表示されます。
withServerQuery を使用して Duplication を最小化する
ここまでで、React Server Component で data に query を実行し、それを client component に渡して initial query value として使用する方法を学びました。ただし、query logic が 2 か所、Home React Server Component と Users client component に存在していることに気付くでしょう。特に一方の location の query を変更して、もう一方の update を忘れると、maintenance が難しくなります。
duplication を避けるため、Squid React SDK は withServerQuery function を公開しています。この hook は server での data query と client component への data の渡しを処理します。
新しい withServerQuery function を使用するように Home page を update します。この function は 3 つの argument を取ります。
- query data を受け取る client component。
- 実行する query。
- query update を subscribe するかどうか。
この function は次に、Users component の render に使用できる Higher Order Component を生成します。新しい function を含めるよう app/page.tsx を update します。
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 />;
}
この新しい function を使用するには、Users component にいくつかの change が必要です。
- component から
useQueryhook を remove します。data は wrappingwithServerQueryfunction から提供されます。 usersprop の name をdataに変更します。withServerQueryは wrap する client component にdataprop を渡します。- prop type を
WithQueryProps<User>に update します。これは実質的に{ data: Array<User> }へ translate される wrapper です。 if (loading) {...}とif (error) {...}conditional を remove します。component の render 前に data が load されるため、これらは不要です。
その結果、新しい components/users.tsx component は次のようになります。
'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 app を reload します。これで Loading… indicator や data の flicker なしで、すべての user を確認できます。さらに、Insert をクリックしても user list は dynamic に update されます。
query の subscription の動作を experiment するには、withServerQuery function 内の true を false に変更してみてください。この場合も load 時には user data が表示されますが、user の insert による user list の live update は発生しません（page の reload 後には user が表示されます）。これは、client component で change を subscribe しなくなり、実際には Squid query が client でまったく実行されなくなるためです。
change を subscribe しない場合、実質的に Squid を server side のみで使用します。これは、特に real-time data update が不要な場合には完全に valid な use case です。
Server に Data を Insert する
server で data に query を実行するだけでなく、router handler と server action 内でも Squid を使用できます。server から user を insert してみましょう。
Route Handler
app/api/insert/route.ts の下に新しい router handler を作成し、この route を以下の code に置き換えます。
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);
}
この code は Users component の insertUser function と非常によく似ています。目的は同じで、built-in database に user を作成しますが、今回は client ではなく server で実行されます。
client からこの function を call するには、insertUser function を以下に update します。
export default function Home(...) {
...
const insertUser = async () => {
await fetch("api/insert", { method: "POST" });
};
...
}
“Insert” button をクリックすると、server から user が insert されます！
Optimistic Update
button をクリックしてから、新しく insert された user が user list に表示されるまでに小さな delay があることに気付くでしょう。これは Squid が client で optimistic update を自動処理する方法によるものです。
client-side implementation の insertUser では、insert は client で直接行われます。この場合、Squid は optimistically に insert を実行するため、insert request が in flight 中でも新しい user が即座に表示されます。何らかの理由で insert が failure した場合、Squid は optimistic insert を rollback します。
server から insert する場合、optimistic update の benefit は失われます。一般に、API route 内で Squid を使用して insert はできますが、client から直接 insert・update する方が user experience が優れていることが多いです。
Server Action
Router Handler に加え、App Router の使用時は experimental Server Actions をサポートします。Server Actions を使用すると、server で dynamic に実行できる function を記述できます。
Server Actions をサポートするには、next.config.js を update します。
module.exports = {
experimental: {
serverActions: true,
},
};
actions という新しい folder を作成し、以下の code を持つ insert.tsx file を追加します。use server directive は、この file が 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(),
});
}
client では、form の submit により Server Action を import・call できます。作成した action insertUser function を call するには、以下のように Users component を update します。
"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>
);
}
Server Action は server-side で実行されるため、optimistic update をサポートしません。