Tipagem de Server Components

Q: Um Server Component pode ser uma função async?

Sim. Server Components podem ser async e retornar Promise. Isso é exclusivo de RSC -- client components não podem ser async.

Q: O que é useActionState e como ele substitui useFormState?

useActionState (React 19) retorna [state, formAction, isPending]. Ele substitui o antigo useFormState com inferência de tipo completa e um flag de pendência embutido.

Q: Posso usar React.FC para Server Components?

Não. React.FC não suporta componentes assíncronos. Use declarações de função regulares: async function Page() { ... }.

Q: O que formData.get() retorna e como eu o restrinjo?

Retorna FormDataEntryValue | null, que é string | File | null. Sempre verifique typeof value === "string" antes de usá-lo como string.

Receita

Tipagem de React Server Components (RSC), componentes assíncronos e Server Actions no Next.js. Entenda como o TypeScript funciona com a fronteira servidor/cliente.

Exemplo de Trabalho

// app/users/page.tsx - Server Component Assíncrono
type User = {
  id: string;
  name: string;
  email: string;
};
 
async function getUsers(): Promise<User[]> {
  const res = await fetch("https://api.example.com/users", {
    cache: "force-cache",
  });
  if (!res.ok) throw new Error("Falha ao buscar usuários");
  return res.json() as Promise<User[]>;
}
 
export default async function UsersPage() {
  const users = await getUsers();
 
  return (
    <main>
      <h1>Usuários</h1>
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </main>
  );
}

// Server Action com params tipados
"use server";
 
type CreateUserInput = {
  name: string;
  email: string;
};
 
type ActionResult = {
  success: boolean;
  message: string;
};
 
export async function createUser(input: CreateUserInput): Promise<ActionResult> {
  // Valida e salva no banco de dados
  if (!input.name || !input.email) {
    return { success: false, message: "Nome e email são obrigatórios" };
  }
 
  // ... operação de banco de dados
  return { success: true, message: "Usuário criado" };
}

// Client component consumindo a Server Action
"use client";
 
import { useActionState } from "react";
import { createUser } from "./actions";
 
export function CreateUserForm() {
  const [state, formAction, isPending] = useActionState(
    async (_prevState: ActionResult | null, formData: FormData) => {
      const result = await createUser({
        name: formData.get("name") as string,
        email: formData.get("email") as string,
      });
      return result;
    },
    null
  );
 
  return (
    <form action={formAction}>
      <input name="name" required />
      <input name="email" type="email" required />
      <button type="submit" disabled={isPending}>
        {isPending ? "Criando..." : "Criar Usuário"}
      </button>
      {state?.message && <p>{state.message}</p>}
    </form>
  );
}

Mergulho Profundo

Como Funciona

Server Components podem ser funções async. O TypeScript permite async function Page() que retorna Promise<JSX.Element>. Isso é exclusivo de RSC -- client components não podem ser assíncronos.
Server Actions são funções assíncronas marcadas com "use server". Elas rodam no servidor, mas podem ser chamadas de client components. O TypeScript garante os tipos de parâmetro e retorno através da fronteira.
As diretivas "use client" e "use server" criam limites de serialização. Apenas tipos serializáveis (strings, números, objetos simples, arrays, Date, FormData, etc.) podem cruzar esses limites.
useActionState (React 19) substitui o antigo useFormState. Ele retorna [state, formAction, isPending] com inferência de tipo completa da função de ação.

Variações

Parâmetros de página tipados (Next.js 15):

// app/users/[id]/page.tsx
type PageProps = {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
export default async function UserPage({ params, searchParams }: PageProps) {
  const { id } = await params;
  const { tab } = await searchParams;
 
  const user = await getUser(id);
 
  return <div>{user.name}</div>;
}

Server Action com FormData:

"use server";
 
export async function submitForm(formData: FormData): Promise<ActionResult> {
  const name = formData.get("name");
  const email = formData.get("email");
 
  if (typeof name !== "string" || typeof email !== "string") {
    return { success: false, message: "Dados do formulário inválidos" };
  }
 
  // ... processar
  return { success: true, message: "Enviado" };
}

Componente de layout tipado:

// app/layout.tsx
type RootLayoutProps = {
  children: React.ReactNode;
};
 
export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Notas de TypeScript

No Next.js 15, params e searchParams são tipos Promise que precisam ser aguardados (awaited). Esta é uma mudança que quebra a compatibilidade com o Next.js 14.
Server Actions só podem aceitar e retornar valores serializáveis. Funções, instâncias de classe e Symbols não podem cruzar a fronteira.
O tipo React.FC não suporta componentes assíncronos. Use declarações de função regulares para Server Components.

Armadilhas

Importar uma Server Action em um client component funciona, mas passar uma função de cliente para um Server Component não funciona. Funções não são serializáveis.
formData.get() retorna FormDataEntryValue | null (que é string | File | null). Sempre valide e restrinja o tipo.
Esquecer "use server" em um arquivo de ação significa que a função roda no cliente, o que falhará se usar APIs exclusivas do servidor como acesso a banco de dados.
Server Components não podem usar hooks (useState, useEffect, etc.). O TypeScript não pegará isso -- é um erro de tempo de execução.

Alternativas

Abordagem	Prós	Contras
Server Components Assíncronos	Busca de dados direta, zero JS no cliente	Não pode usar hooks ou APIs do navegador
Server Actions	Mutações type-safe, aprimoramento progressivo	Apenas parâmetros e retornos serializáveis
API Route Handlers	Controle total de HTTP, qualquer cliente pode chamar	Fetch manual + tipagem no cliente
tRPC	Type safety de ponta a ponta	Dependência e configuração adicionais
`getServerSideProps` no servidor (Pages Router)	Padrão familiar	Apenas Pages Router, sendo descontinuado

FAQs

Um Server Component pode ser uma função async?

Sim. Server Components podem ser async e retornar Promise<JSX.Element>.
Isso é exclusivo de RSC -- client components não podem ser async.

O que é a diretiva `"use server"` e onde ela vai?

Ela marca um arquivo (ou função individual) como Server Action.
Coloque-a no topo do arquivo ou no início do corpo da função.
Server Actions rodam no servidor, mas podem ser chamadas de client components.

Que tipos podem cruzar a fronteira servidor/cliente?

Apenas tipos serializáveis: strings, números, booleanos, objetos simples, arrays, Date, FormData.
Funções, instâncias de classe, Symbols e Maps não podem cruzar a fronteira.

Como eu tipoo os parâmetros de página no Next.js 15?

type PageProps = {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
export default async function Page({ params, searchParams }: PageProps) {
  const { id } = await params;
}

O que é `useActionState` e como ele substitui `useFormState`?

useActionState (React 19) retorna [state, formAction, isPending].
Ele substitui o antigo useFormState com inferência de tipo completa e um flag de pendência embutido.

Armadilha: O que acontece se eu esquecer a diretiva `"use server"` em um arquivo de ação?

A função rodará no cliente em vez de no servidor.
Se usar APIs exclusivas do servidor (banco de dados, segredos), falhará em tempo de execução.

Posso usar `React.FC` para Server Components?

Não. React.FC não suporta componentes assíncronos.
Use declarações de função regulares: async function Page() { ... }.

Armadilha: Server Components podem usar hooks como useState ou useEffect?

Não. Server Components não podem usar nenhum hook.
O TypeScript não pegará isso -- produz um erro de tempo de execução, não um erro de tempo de compilação.

Como devo tipar um componente de layout?

type RootLayoutProps = {
  children: React.ReactNode;
};
 
export default function RootLayout({ children }: RootLayoutProps) {
  return <html><body>{children}</body></html>;
}

O que `formData.get()` retorna e como eu o restrinjo?

Retorna FormDataEntryValue | null, que é string | File | null.
Sempre verifique typeof value === "string" antes de usá-lo como string.

Posso passar uma função de cliente para um Server Component?

Não. Funções não são serializáveis e não podem cruzar a fronteira cliente-servidor.
Importar uma Server Action em um client component funciona, mas o inverso não.

Como eu tipoo uma Server Action que aceita FormData?

"use server";
 
export async function submitForm(formData: FormData): Promise<ActionResult> {
  const name = formData.get("name");
  if (typeof name !== "string") {
    return { success: false, message: "Inválido" };
  }
  // processar...
  return { success: true, message: "Feito" };
}

// app/users/page.tsx - Server Component Assíncrono
type User = {
  id: string;
  name: string;
  email: string;
};
 
async function getUsers(): Promise<User[]> {
  const res = await fetch("https://api.example.com/users", {
    cache: "force-cache",
  });
  if (!res.ok) throw new Error("Falha ao buscar usuários");
  return res.json() as Promise<User[]>;
}
 
export default async function UsersPage() {
  const users = await getUsers();
 
  return (
    <main>
      <h1>Usuários</h1>
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </main>
  );
}

// Server Action com params tipados
"use server";
 
type CreateUserInput = {
  name: string;
  email: string;
};
 
type ActionResult = {
  success: boolean;
  message: string;
};
 
export async function createUser(input: CreateUserInput): Promise<ActionResult> {
  // Valida e salva no banco de dados
  if (!input.name || !input.email) {
    return { success: false, message: "Nome e email são obrigatórios" };
  }
 
  // ... operação de banco de dados
  return { success: true, message: "Usuário criado" };
}

// Client component consumindo a Server Action
"use client";
 
import { useActionState } from "react";
import { createUser } from "./actions";
 
export function CreateUserForm() {
  const [state, formAction, isPending] = useActionState(
    async (_prevState: ActionResult | null, formData: FormData) => {
      const result = await createUser({
        name: formData.get("name") as string,
        email: formData.get("email") as string,
      });
      return result;
    },
    null
  );
 
  return (
    <form action={formAction}>
      <input name="name" required />
      <input name="email" type="email" required />
      <button type="submit" disabled={isPending}>
        {isPending ? "Criando..." : "Criar Usuário"}
      </button>
      {state?.message && <p>{state.message}</p>}
    </form>
  );
}

Mergulho Profundo

Como Funciona

Server Components podem ser funções async. O TypeScript permite async function Page() que retorna Promise<JSX.Element>. Isso é exclusivo de RSC -- client components não podem ser assíncronos.
Server Actions são funções assíncronas marcadas com "use server". Elas rodam no servidor, mas podem ser chamadas de client components. O TypeScript garante os tipos de parâmetro e retorno através da fronteira.
As diretivas "use client" e "use server" criam limites de serialização. Apenas tipos serializáveis (strings, números, objetos simples, arrays, Date, FormData, etc.) podem cruzar esses limites.
useActionState (React 19) substitui o antigo useFormState. Ele retorna [state, formAction, isPending] com inferência de tipo completa da função de ação.

Variações

Parâmetros de página tipados (Next.js 15):

// app/users/[id]/page.tsx
type PageProps = {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
export default async function UserPage({ params, searchParams }: PageProps) {
  const { id } = await params;
  const { tab } = await searchParams;
 
  const user = await getUser(id);
 
  return <div>{user.name}</div>;
}

Server Action com FormData:

"use server";
 
export async function submitForm(formData: FormData): Promise<ActionResult> {
  const name = formData.get("name");
  const email = formData.get("email");
 
  if (typeof name !== "string" || typeof email !== "string") {
    return { success: false, message: "Dados do formulário inválidos" };
  }
 
  // ... processar
  return { success: true, message: "Enviado" };
}

Componente de layout tipado:

// app/layout.tsx
type RootLayoutProps = {
  children: React.ReactNode;
};
 
export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Notas de TypeScript

No Next.js 15, params e searchParams são tipos Promise que precisam ser aguardados (awaited). Esta é uma mudança que quebra a compatibilidade com o Next.js 14.
Server Actions só podem aceitar e retornar valores serializáveis. Funções, instâncias de classe e Symbols não podem cruzar a fronteira.
O tipo React.FC não suporta componentes assíncronos. Use declarações de função regulares para Server Components.

Armadilhas

Importar uma Server Action em um client component funciona, mas passar uma função de cliente para um Server Component não funciona. Funções não são serializáveis.
formData.get() retorna FormDataEntryValue | null (que é string | File | null). Sempre valide e restrinja o tipo.
Esquecer "use server" em um arquivo de ação significa que a função roda no cliente, o que falhará se usar APIs exclusivas do servidor como acesso a banco de dados.
Server Components não podem usar hooks (useState, useEffect, etc.). O TypeScript não pegará isso -- é um erro de tempo de execução.

Alternativas

Abordagem	Prós	Contras
Server Components Assíncronos	Busca de dados direta, zero JS no cliente	Não pode usar hooks ou APIs do navegador
Server Actions	Mutações type-safe, aprimoramento progressivo	Apenas parâmetros e retornos serializáveis
API Route Handlers	Controle total de HTTP, qualquer cliente pode chamar	Fetch manual + tipagem no cliente
tRPC	Type safety de ponta a ponta	Dependência e configuração adicionais
`getServerSideProps` no servidor (Pages Router)	Padrão familiar	Apenas Pages Router, sendo descontinuado

FAQs

Um Server Component pode ser uma função async?

Sim. Server Components podem ser async e retornar Promise<JSX.Element>.
Isso é exclusivo de RSC -- client components não podem ser async.

O que é a diretiva `"use server"` e onde ela vai?

Ela marca um arquivo (ou função individual) como Server Action.
Coloque-a no topo do arquivo ou no início do corpo da função.
Server Actions rodam no servidor, mas podem ser chamadas de client components.

Que tipos podem cruzar a fronteira servidor/cliente?

Apenas tipos serializáveis: strings, números, booleanos, objetos simples, arrays, Date, FormData.
Funções, instâncias de classe, Symbols e Maps não podem cruzar a fronteira.

Como eu tipoo os parâmetros de página no Next.js 15?

type PageProps = {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};
 
export default async function Page({ params, searchParams }: PageProps) {
  const { id } = await params;
}

O que é `useActionState` e como ele substitui `useFormState`?

useActionState (React 19) retorna [state, formAction, isPending].
Ele substitui o antigo useFormState com inferência de tipo completa e um flag de pendência embutido.

Armadilha: O que acontece se eu esquecer a diretiva `"use server"` em um arquivo de ação?

A função rodará no cliente em vez de no servidor.
Se usar APIs exclusivas do servidor (banco de dados, segredos), falhará em tempo de execução.

Posso usar `React.FC` para Server Components?

Não. React.FC não suporta componentes assíncronos.
Use declarações de função regulares: async function Page() { ... }.

Armadilha: Server Components podem usar hooks como useState ou useEffect?

Não. Server Components não podem usar nenhum hook.
O TypeScript não pegará isso -- produz um erro de tempo de execução, não um erro de tempo de compilação.

Como devo tipar um componente de layout?

type RootLayoutProps = {
  children: React.ReactNode;
};
 
export default function RootLayout({ children }: RootLayoutProps) {
  return <html><body>{children}</body></html>;
}

O que `formData.get()` retorna e como eu o restrinjo?

Retorna FormDataEntryValue | null, que é string | File | null.
Sempre verifique typeof value === "string" antes de usá-lo como string.

Posso passar uma função de cliente para um Server Component?

Não. Funções não são serializáveis e não podem cruzar a fronteira cliente-servidor.
Importar uma Server Action em um client component funciona, mas o inverso não.

Como eu tipoo uma Server Action que aceita FormData?

"use server";
 
export async function submitForm(formData: FormData): Promise<ActionResult> {
  const name = formData.get("name");
  if (typeof name !== "string") {
    return { success: false, message: "Inválido" };
  }
  // processar...
  return { success: true, message: "Feito" };
}

Tipagem de Server Components

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Tipagem de Server Components

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Tipagem de Server Components

Buscar na documentação

Tipagem de Server Components