Agent X-Ray

Notes Skills About

Skills/

正在取…

INSTALL

FILES

本页目录

苏ICP备2025204887号-2

Skills/开发框架/encore-frontend

encore-frontend精选

把前端接到 Encore.ts 后端:encore gen client 生成 TS 客户端、CORS、鉴权透传

1 个文件 · 7.0 KB · 更新于 2026-09-03 · 出处 encoredev/skills ↗

GitHub ↗下载 zip · 3 KB

INSTALL

npx skills add encoredev/skills --skill encore-frontend

copy

装进 .claude/skills/encore-frontend/;Codex 读 .agents/skills/,同一目录结构。

FILES

▾encore-frontend/

SKILL.md7.0 KB

本页目录

Instructions

SKILL.mdmarkdown · 7.0 KB · 257 行

copy

nameencore-frontenddescriptionConnect a frontend application (React, Next.js, Vue, Svelte, etc.) to an Encore.ts backend.when_to_useUser wants to generate a TypeScript API client for the browser (`encore gen client`), call Encore endpoints from React/Next.js/Vue/Svelte/SvelteKit/Remix/Astro, configure CORS in `encore.app`, or wire authentication tokens through a generated client. Trigger phrases: "TypeScript client", "API client", "Next.js frontend", "React frontend", "encore gen client", "CORS", "browser fetch", "SPA", "frontend can call this backend".

Frontend Integration with Encore

Instructions

Encore provides tools to connect your frontend applications to your backend APIs.

Generate a TypeScript Client

bash

# Generate client for local development
encore gen client --output=./frontend/src/client.ts --env=local

# Generate client for a deployed environment
encore gen client --output=./frontend/src/client.ts --env=staging

This generates a fully typed client based on your API definitions.

Using the Generated Client

typescript

// frontend/src/client.ts is auto-generated
import Client from "./client";

const client = new Client("http://localhost:4000");

// Fully typed API calls
const user = await client.user.getUser({ id: "123" });
console.log(user.email);

const newUser = await client.user.createUser({
  email: "new@example.com",
  name: "New User",
});

React Example

tsx

// frontend/src/components/UserProfile.tsx
import { useState, useEffect } from "react";
import Client from "../client";

const client = new Client(import.meta.env.VITE_API_URL);

export function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    client.user.getUser({ id: userId })
      .then(setUser)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

React with TanStack Query

tsx

import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import Client from "../client";

const client = new Client(import.meta.env.VITE_API_URL);

export function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ["user", userId],
    queryFn: () => client.user.getUser({ id: userId }),
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>{user.name}</div>;
}

export function CreateUserForm() {
  const queryClient = useQueryClient();
  
  const mutation = useMutation({
    mutationFn: (data: { email: string; name: string }) => 
      client.user.createUser(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    mutation.mutate({
      email: formData.get("email") as string,
      name: formData.get("name") as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <input name="name" required />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}

Next.js Server Components

tsx

// app/users/[id]/page.tsx
import Client from "@/lib/client";

const client = new Client(process.env.API_URL);

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await client.user.getUser({ id: params.id });
  
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Configure CORS in your encore.app file:

json

{
    "id": "my-app",
    "global_cors": {
        "allow_origins_with_credentials": [
            "http://localhost:3000",
            "https://myapp.com",
            "https://*.myapp.com"
        ]
    }
}

Option	Description
allow_origins_without_credentials	Origins allowed for non-credentialed requests (default: ["*"])
allow_origins_with_credentials	Origins allowed for credentialed requests (cookies, auth headers)
allow_headers	Additional request headers to allow
expose_headers	Additional response headers to expose
debug	Enable CORS debug logging

Authentication from Frontend

For authenticated requests, pass the Authorization header:

typescript

// Using fetch
const response = await fetch("http://localhost:4000/profile", {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});

// Or include credentials for cookie-based auth
const response = await fetch("http://localhost:4000/profile", {
  credentials: "include",
});

With TanStack Query, configure a default fetcher:

typescript

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryFn: async ({ queryKey }) => {
        const response = await fetch(queryKey[0] as string, {
          headers: { Authorization: `Bearer ${getToken()}` },
        });
        if (!response.ok) throw new Error("Request failed");
        return response.json();
      },
    },
  },
});

If you prefer not to use the generated client:

typescript

async function getUser(id: string) {
  const response = await fetch(`http://localhost:4000/users/${id}`);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  return response.json();
}

async function createUser(email: string, name: string) {
  const response = await fetch("http://localhost:4000/users", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, name }),
  });
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  return response.json();
}

Environment Variables

bash

# .env.local (Next.js)
NEXT_PUBLIC_API_URL=http://localhost:4000

# .env (Vite)
VITE_API_URL=http://localhost:4000

Use encore gen client to generate typed API clients
Regenerate the client when your API changes
Configure CORS in encore.app for production domains
Use allow_origins_with_credentials for authenticated requests
Include Authorization header for token-based auth
Use credentials: "include" for cookie-based auth
Use environment variables for API URLs (different per environment)
The generated client handles errors and types automatically

Frontend Integration with Encore

Instructions

Generate a TypeScript Client

Using the Generated Client

React Example

React with TanStack Query

Next.js Server Components

CORS Configuration

CORS Options

Authentication from Frontend

Using Plain Fetch

Environment Variables

Guidelines