volcano-nextjs

Use for Next.js on Volcano and for web apps, pages, dashboards, boards, galleries, full-stack UIs, public HTTP routes, redirects, webhook ingress, middleware, API routes, server actions, and client or server SDK separation.

跳到安装

仓库: Kong/volcano-agentic-plugins
最近来源活动: 2026年7月26日 01:30
检测到的 SKILL.md 语言: 英语
星标: 0
分支: 0

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/Kong/volcano-agentic-plugins --skill volcano-nextjs

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

SKILL.md

来源说明 · 只读预览

name	volcano-nextjs
description	Use for Next.js on Volcano and for web apps, pages, dashboards, boards, galleries, full-stack UIs, public HTTP routes, redirects, webhook ingress, middleware, API routes, server actions, and client or server SDK separation.

Volcano Next.js Skill

Role

Implement Volcano SDK in Next.js with strict client/server separation and middleware-first auth checks. This skill is self-contained: env contract, shared client pattern, AuthContext template, middleware helpers, app/pages router examples, server actions, OAuth callback, and SSR safety are embedded.

Workflow

Centralize the Volcano client behind a getVolcano() helper used by all client components.
Use middleware helpers (createServerClient, withAuth, getTokenFromRequest) for server/middleware auth checks.
Keep browser-only auth actions (OAuth initiation, localStorage session) out of server-only code.
Validate redirect/protection behavior and hydration edge cases.

Environment Contract

.env.local:

NEXT_PUBLIC_VOLCANO_API_URL=https://api.yourproject.volcano.dev
NEXT_PUBLIC_VOLCANO_ANON_KEY=ak-your-anon-key
NEXT_PUBLIC_VOLCANO_DATABASE_NAME=your-database

NEXT_PUBLIC_* vars are exposed to both client and server.
Server-only secrets MUST NOT have the NEXT_PUBLIC_ prefix.

Execution Environments

Environment	SDK usage
Client Components	Full SDK — auth, queries, storage, realtime
Server Components	No direct SDK — call API routes, server actions, or middleware-derived data
Middleware	`@volcano.dev/sdk/next/middleware` helpers
API Routes / Route Handlers	Server client for token validation; full SDK with the bearer token for queries

Shared Client Pattern (lib/volcano.ts)

// lib/volcano.ts
import { VolcanoAuth } from '@volcano.dev/sdk';

let volcano: VolcanoAuth | null = null;

export function getVolcano(): VolcanoAuth {
  if (!volcano) {
    volcano = new VolcanoAuth({
      apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
      anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    });
    volcano.database(process.env.NEXT_PUBLIC_VOLCANO_DATABASE_NAME!);
  }
  return volcano;
}

AuthContext Provider (Client Component)

// context/AuthContext.tsx
'use client';

import { createContext, useContext, useEffect, useState, useCallback, ReactNode } from 'react';
import { getVolcano } from '@/lib/volcano';
import type { User } from '@volcano.dev/sdk';

interface AuthContextType {
  user: User | null;
  loading: boolean;
  signIn: (email: string, password: string) => Promise<void>;
  signUp: (email: string, password: string) => Promise<void>;
  signOut: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState< | >();
   [loading, setLoading] = ();

  ( {
     volcano = ();

    
    volcano.().( {
      (user);
      ();
    });

    
     unsubscribe = volcano..(setUser);
      ();
  }, []);

   signIn = ( (: , : ) => {
     { error } =  ()..({ email, password });
     (error)  error;
  }, []);

   signUp = ( (: , : ) => {
     { error } =  ()..({ email, password });
     (error)  error;
  }, []);

   signOut = ( () => {
     ()..();
  }, []);

   (
    
  );
}

  () {
   ctx = ();
   (!ctx)   ();
   ctx;
}

Wire in app/layout.tsx:

import { AuthProvider } from '@/context/AuthContext';

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

Protected Page (Client Component)

'use client';
import { useAuth } from '@/context/AuthContext';
import { useRouter } from 'next/navigation';
import { useEffect, useState } from 'react';
import { getVolcano } from '@/lib/volcano';

export default function DashboardPage() {
  const { user, loading } = useAuth();
  const router = useRouter();
  const [posts, setPosts] = useState<any[]>([]);

  useEffect(() => {
    if (!loading && !user) router.push('/login');
  }, [user, loading, router]);

  useEffect(() => {
    if (!user) return;
    getVolcano()
      .from('posts')
      .select('*')
      .order('created_at', { ascending: false })
      .limit(10)
      .then(({ data }) => setPosts(data ?? []));
  }, [user]);

  if (loading) return ;
   (!user)  ;

   (
    
  );
}

Middleware (Edge auth checks)

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { createServerClient, withAuth } from '@volcano.dev/sdk/next/middleware';

export async function middleware(request: NextRequest) {
  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });

  const user = await withAuth(request, client);

  if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  if (request.nextUrl.pathname === '/login' && user) {
    return NextResponse.redirect(new (, request.));
  }
   .();
}

  config = {
  : [, ],
};

Middleware Helpers API

import {
  createServerClient,
  withAuth,
  getTokenFromRequest,
  isBrowser,
  isServer,
} from '@volcano.dev/sdk/next/middleware';

const client = createServerClient({ anonKey, apiUrl }); // apiUrl optional

const user = await withAuth(request, client);     // null when invalid/missing
const token = getTokenFromRequest(request);       // Authorization header or cookie
const { user, error } = await client.getUser(token);
const { accessToken, refreshToken, error } = await client.refreshToken(oldRefreshToken);

if (isBrowser()) { /* ... */ }
if (isServer())  { /* ... */ }

API Routes — App Router (Route Handlers)

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createServerClient, getTokenFromRequest } from '@volcano.dev/sdk/next/middleware';
import { VolcanoAuth } from '@volcano.dev/sdk';

export async function GET(request: NextRequest) {
  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });

  const token = getTokenFromRequest(request);
  if (!token) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const { user, error } = await client.getUser(token);
  if (error || !user) return NextResponse.json({ error: 'Invalid token' }, { status: 401 });

  // Use the SDK with the bearer token for queries / function calls
   volcano =  ({
    : process..!,
    : process..!,
    : token,
  });

   { data, : queryError } =  volcano..();
   (queryError)  .({ : queryError. }, { :  });

   .({ : data });
}

API Routes — Pages Router

// pages/api/posts.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { VolcanoAuth } from '@volcano.dev/sdk';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

  const volcano = new VolcanoAuth({
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    accessToken: token,
  });
  volcano.database(process.env.NEXT_PUBLIC_VOLCANO_DATABASE_NAME!);

  const { data, error } = await volcano
    .from('posts')
    .()
    .(, { :  });
   (error)  res.().({ : error. });

   res.().({ : data });
}

Cookie Sync — required for Server Actions and middleware token reads

The SDK stores tokens in localStorage by default. Server Actions, route handlers, and middleware run on the server and cannot read localStorage — they read cookies. Add a small client component that mirrors the access token to a cookie whenever auth state changes:

// components/CookieSync.tsx
'use client';
import { useEffect } from 'react';
import { getVolcano } from '@/lib/volcano';

export function CookieSync() {
  useEffect(() => {
    const volcano = getVolcano();
    const sync = (token: string | null) => {
      const base = 'Path=/; SameSite=Lax; Secure';
      document.cookie = token
        ? `volcano_access_token=${token}; ${base}; Max-Age=3600`
        : `volcano_access_token=; ${base}; Max-Age=0`;
    };
    sync(volcano.accessToken ?? null);
    const unsub = volcano.auth.onAuthStateChange(() => {
      sync(volcano.accessToken ?? null);
    });
    return () => unsub();
  }, []);
  return null;
}

Mount it once, alongside the AuthProvider:

// app/layout.tsx
import { AuthProvider } from '@/context/AuthContext';
import { CookieSync } from '@/components/CookieSync';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          <CookieSync />
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

Security note: This cookie is JS-readable, which matches the SDK's localStorage exposure — the XSS surface area is identical. For higher-security postures, set an httpOnly cookie from an API route after sign-in and read it server-side via getTokenFromRequest. The client-mirrored pattern shown above is the simplest route to a working Server Action.

Server Components & Server Actions

Server Components don't have localStorage. Three options:

Fetch from API routes (which validate the token).
Use Server Actions with the SDK and the cookie token.
Pass middleware-derived data via headers.

Server Action template

// app/actions.ts
'use server';

import { cookies } from 'next/headers';
import { createServerClient } from '@volcano.dev/sdk/next/middleware';
import { VolcanoAuth } from '@volcano.dev/sdk';

export async function getPosts() {
  const cookieStore = cookies();
  const token = cookieStore.get('volcano_access_token')?.value;
  if (!token) throw new Error('Not authenticated');

  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });
  const { user, error } = await client.getUser(token);
  if (error || !user) throw new Error('Invalid session');

  const volcano = new VolcanoAuth({
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
    : process..!,
    : token,
  });
  volcano.(process..!);

   { data } =  volcano
    .()
    .()
    .(, { :  })
    .();
   data;
}

// app/posts/page.tsx
import { getPosts } from '@/app/actions';

export default async function PostsPage() {
  const posts = await getPosts();
  return <ul>{posts?.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}

Realtime in Next.js (Client Component required)

'use client';
import { useEffect, useState } from 'react';
import { VolcanoRealtime } from '@volcano.dev/sdk/realtime';
import { getVolcano } from '@/lib/volcano';
import { useAuth } from '@/context/AuthContext';

export function LivePosts() {
  const { user } = useAuth();
  const [posts, setPosts] = useState<any[]>([]);

  useEffect(() => {
    if (!user) return;
    const volcano = getVolcano();

    volcano
      .from('posts')
      .select('*')
      .order('created_at', { ascending: false })
      .then(({ data }) => setPosts(data ?? []));

    const realtime = new VolcanoRealtime({
      apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
      anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
      accessToken: volcano.!,
    });

    realtime.().( {
       channel = realtime.(, { :  });
      channel.(, , , 
        ( [c., ...cur]));
      channel.(, , , 
        ( cur.( (p. === c.. ? c. : p))));
      channel.(, , , 
        ( cur.( p. !== c..)));
      channel.();
    });

      { realtime.(); };
  }, [user]);

   ;
}

Default Signup & Login Pages

When the prompt doesn't specify signup/login page design, apply the volcano-auth "Default Signup & Login Page UX" — including the default signup-success alert — on top of the AuthContext from this skill.

// app/signup/page.tsx — default signup page with a success alert
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import Link from 'next/link';
import { useAuth } from '@/context/AuthContext';

export default function SignupPage() {
  const { signUp } = useAuth();
  const router = useRouter();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
    try {
      await signUp(email, password);
      (); 
      ( router.(), );
    }  (: ) {
      (err.);
    }
  };

   (
    
  );
}

// app/login/page.tsx — default login page (email/password)
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import Link from 'next/link';
import { useAuth } from '@/context/AuthContext';

export default function LoginPage() {
  const { signIn } = useAuth();
  const router = useRouter();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
    try {
      await signIn(email, password);
      router.push('/dashboard');
    } catch (err: ) {
      (err.);
    }
  };

   (
    
  );
}

OAuth in Next.js

OAuth initiation must be in a Client Component; the callback page reconciles the tokens. Add the OAuth button(s) to the default login page above (or use standalone, as shown) — don't replace the email/password form unless the user asks for OAuth-only login.

// Add to app/login/page.tsx (or standalone) — OAuth button
'use client';
import { getVolcano } from '@/lib/volcano';

export function GoogleSignInButton() {
  return (
    <button onClick={() => getVolcano().auth.signInWithGoogle()}>
      Sign in with Google
    </button>
  );
}

// app/auth/callback/page.tsx
'use client';
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { getVolcano } from '@/lib/volcano';

export default function AuthCallbackPage() {
  const router = useRouter();
  useEffect(() => {
    getVolcano().initialize().then(({ user }) => {
      router.push(user ? '/dashboard' : '/login?error=auth_failed');
    });
  }, [router]);
  return <div>Completing sign in...</div>;
}

SSR Safety

volcano.auth.signInWith* (OAuth) only works in browser; calling it server-side throws.
The SDK rejects service keys (sk-...) in browser environments.
Use isBrowser() / isServer() from middleware helpers when branching.

Best Practices

Single client instance via getVolcano(). Don't new VolcanoAuth(...) in components.
Loading state is a first-class case — don't render protected UI before useAuth().loading === false.
Pair connect() with disconnect() for realtime in useEffect cleanup.
Validate tokens server-side — do not trust client-supplied user state in API routes / actions.
Use NEXT_PUBLIC_ only for non-secrets; service keys never get this prefix.

Verification Checklist

Client/server responsibilities are clear and correct.
Middleware uses withAuth (or equivalent) before allowing protected routes.
Server components fetch via API routes / server actions / middleware data — never call browser SDK methods directly.
Imports, env vars, dependencies, and init order are consistent.
Realtime is wrapped in a Client Component with proper cleanup.

Optional Fallback References

name	volcano-nextjs
description	Use for Next.js on Volcano and for web apps, pages, dashboards, boards, galleries, full-stack UIs, public HTTP routes, redirects, webhook ingress, middleware, API routes, server actions, and client or server SDK separation.

Volcano Next.js Skill

Role

Workflow

Centralize the Volcano client behind a getVolcano() helper used by all client components.
Use middleware helpers (createServerClient, withAuth, getTokenFromRequest) for server/middleware auth checks.
Keep browser-only auth actions (OAuth initiation, localStorage session) out of server-only code.
Validate redirect/protection behavior and hydration edge cases.

Environment Contract

.env.local:

NEXT_PUBLIC_VOLCANO_API_URL=https://api.yourproject.volcano.dev
NEXT_PUBLIC_VOLCANO_ANON_KEY=ak-your-anon-key
NEXT_PUBLIC_VOLCANO_DATABASE_NAME=your-database

NEXT_PUBLIC_* vars are exposed to both client and server.
Server-only secrets MUST NOT have the NEXT_PUBLIC_ prefix.

Execution Environments

Environment	SDK usage
Client Components	Full SDK — auth, queries, storage, realtime
Server Components	No direct SDK — call API routes, server actions, or middleware-derived data
Middleware	`@volcano.dev/sdk/next/middleware` helpers
API Routes / Route Handlers	Server client for token validation; full SDK with the bearer token for queries

Shared Client Pattern (lib/volcano.ts)

// lib/volcano.ts
import { VolcanoAuth } from '@volcano.dev/sdk';

let volcano: VolcanoAuth | null = null;

export function getVolcano(): VolcanoAuth {
  if (!volcano) {
    volcano = new VolcanoAuth({
      apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
      anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    });
    volcano.database(process.env.NEXT_PUBLIC_VOLCANO_DATABASE_NAME!);
  }
  return volcano;
}

AuthContext Provider (Client Component)

// context/AuthContext.tsx
'use client';

import { createContext, useContext, useEffect, useState, useCallback, ReactNode } from 'react';
import { getVolcano } from '@/lib/volcano';
import type { User } from '@volcano.dev/sdk';

interface AuthContextType {
  user: User | null;
  loading: boolean;
  signIn: (email: string, password: string) => Promise<void>;
  signUp: (email: string, password: string) => Promise<void>;
  signOut: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState< | >();
   [loading, setLoading] = ();

  ( {
     volcano = ();

    
    volcano.().( {
      (user);
      ();
    });

    
     unsubscribe = volcano..(setUser);
      ();
  }, []);

   signIn = ( (: , : ) => {
     { error } =  ()..({ email, password });
     (error)  error;
  }, []);

   signUp = ( (: , : ) => {
     { error } =  ()..({ email, password });
     (error)  error;
  }, []);

   signOut = ( () => {
     ()..();
  }, []);

   (
    
  );
}

  () {
   ctx = ();
   (!ctx)   ();
   ctx;
}

Wire in app/layout.tsx:

import { AuthProvider } from '@/context/AuthContext';

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

Protected Page (Client Component)

'use client';
import { useAuth } from '@/context/AuthContext';
import { useRouter } from 'next/navigation';
import { useEffect, useState } from 'react';
import { getVolcano } from '@/lib/volcano';

export default function DashboardPage() {
  const { user, loading } = useAuth();
  const router = useRouter();
  const [posts, setPosts] = useState<any[]>([]);

  useEffect(() => {
    if (!loading && !user) router.push('/login');
  }, [user, loading, router]);

  useEffect(() => {
    if (!user) return;
    getVolcano()
      .from('posts')
      .select('*')
      .order('created_at', { ascending: false })
      .limit(10)
      .then(({ data }) => setPosts(data ?? []));
  }, [user]);

  if (loading) return ;
   (!user)  ;

   (
    
  );
}

Middleware (Edge auth checks)

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { createServerClient, withAuth } from '@volcano.dev/sdk/next/middleware';

export async function middleware(request: NextRequest) {
  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });

  const user = await withAuth(request, client);

  if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  if (request.nextUrl.pathname === '/login' && user) {
    return NextResponse.redirect(new (, request.));
  }
   .();
}

  config = {
  : [, ],
};

Middleware Helpers API

import {
  createServerClient,
  withAuth,
  getTokenFromRequest,
  isBrowser,
  isServer,
} from '@volcano.dev/sdk/next/middleware';

const client = createServerClient({ anonKey, apiUrl }); // apiUrl optional

const user = await withAuth(request, client);     // null when invalid/missing
const token = getTokenFromRequest(request);       // Authorization header or cookie
const { user, error } = await client.getUser(token);
const { accessToken, refreshToken, error } = await client.refreshToken(oldRefreshToken);

if (isBrowser()) { /* ... */ }
if (isServer())  { /* ... */ }

API Routes — App Router (Route Handlers)

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createServerClient, getTokenFromRequest } from '@volcano.dev/sdk/next/middleware';
import { VolcanoAuth } from '@volcano.dev/sdk';

export async function GET(request: NextRequest) {
  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });

  const token = getTokenFromRequest(request);
  if (!token) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const { user, error } = await client.getUser(token);
  if (error || !user) return NextResponse.json({ error: 'Invalid token' }, { status: 401 });

  // Use the SDK with the bearer token for queries / function calls
   volcano =  ({
    : process..!,
    : process..!,
    : token,
  });

   { data, : queryError } =  volcano..();
   (queryError)  .({ : queryError. }, { :  });

   .({ : data });
}

API Routes — Pages Router

// pages/api/posts.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { VolcanoAuth } from '@volcano.dev/sdk';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

  const volcano = new VolcanoAuth({
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    accessToken: token,
  });
  volcano.database(process.env.NEXT_PUBLIC_VOLCANO_DATABASE_NAME!);

  const { data, error } = await volcano
    .from('posts')
    .()
    .(, { :  });
   (error)  res.().({ : error. });

   res.().({ : data });
}

Cookie Sync — required for Server Actions and middleware token reads

// components/CookieSync.tsx
'use client';
import { useEffect } from 'react';
import { getVolcano } from '@/lib/volcano';

export function CookieSync() {
  useEffect(() => {
    const volcano = getVolcano();
    const sync = (token: string | null) => {
      const base = 'Path=/; SameSite=Lax; Secure';
      document.cookie = token
        ? `volcano_access_token=${token}; ${base}; Max-Age=3600`
        : `volcano_access_token=; ${base}; Max-Age=0`;
    };
    sync(volcano.accessToken ?? null);
    const unsub = volcano.auth.onAuthStateChange(() => {
      sync(volcano.accessToken ?? null);
    });
    return () => unsub();
  }, []);
  return null;
}

Mount it once, alongside the AuthProvider:

// app/layout.tsx
import { AuthProvider } from '@/context/AuthContext';
import { CookieSync } from '@/components/CookieSync';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          <CookieSync />
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

Server Components & Server Actions

Server Components don't have localStorage. Three options:

Fetch from API routes (which validate the token).
Use Server Actions with the SDK and the cookie token.
Pass middleware-derived data via headers.

Server Action template

// app/actions.ts
'use server';

import { cookies } from 'next/headers';
import { createServerClient } from '@volcano.dev/sdk/next/middleware';
import { VolcanoAuth } from '@volcano.dev/sdk';

export async function getPosts() {
  const cookieStore = cookies();
  const token = cookieStore.get('volcano_access_token')?.value;
  if (!token) throw new Error('Not authenticated');

  const client = createServerClient({
    anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL,
  });
  const { user, error } = await client.getUser(token);
  if (error || !user) throw new Error('Invalid session');

  const volcano = new VolcanoAuth({
    apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
    : process..!,
    : token,
  });
  volcano.(process..!);

   { data } =  volcano
    .()
    .()
    .(, { :  })
    .();
   data;
}

// app/posts/page.tsx
import { getPosts } from '@/app/actions';

export default async function PostsPage() {
  const posts = await getPosts();
  return <ul>{posts?.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}

Realtime in Next.js (Client Component required)

'use client';
import { useEffect, useState } from 'react';
import { VolcanoRealtime } from '@volcano.dev/sdk/realtime';
import { getVolcano } from '@/lib/volcano';
import { useAuth } from '@/context/AuthContext';

export function LivePosts() {
  const { user } = useAuth();
  const [posts, setPosts] = useState<any[]>([]);

  useEffect(() => {
    if (!user) return;
    const volcano = getVolcano();

    volcano
      .from('posts')
      .select('*')
      .order('created_at', { ascending: false })
      .then(({ data }) => setPosts(data ?? []));

    const realtime = new VolcanoRealtime({
      apiUrl: process.env.NEXT_PUBLIC_VOLCANO_API_URL!,
      anonKey: process.env.NEXT_PUBLIC_VOLCANO_ANON_KEY!,
      accessToken: volcano.!,
    });

    realtime.().( {
       channel = realtime.(, { :  });
      channel.(, , , 
        ( [c., ...cur]));
      channel.(, , , 
        ( cur.( (p. === c.. ? c. : p))));
      channel.(, , , 
        ( cur.( p. !== c..)));
      channel.();
    });

      { realtime.(); };
  }, [user]);

   ;
}

Default Signup & Login Pages

// app/signup/page.tsx — default signup page with a success alert
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import Link from 'next/link';
import { useAuth } from '@/context/AuthContext';

export default function SignupPage() {
  const { signUp } = useAuth();
  const router = useRouter();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
    try {
      await signUp(email, password);
      (); 
      ( router.(), );
    }  (: ) {
      (err.);
    }
  };

   (
    
  );
}

// app/login/page.tsx — default login page (email/password)
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import Link from 'next/link';
import { useAuth } from '@/context/AuthContext';

export default function LoginPage() {
  const { signIn } = useAuth();
  const router = useRouter();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
    try {
      await signIn(email, password);
      router.push('/dashboard');
    } catch (err: ) {
      (err.);
    }
  };

   (
    
  );
}

OAuth in Next.js

// Add to app/login/page.tsx (or standalone) — OAuth button
'use client';
import { getVolcano } from '@/lib/volcano';

export function GoogleSignInButton() {
  return (
    <button onClick={() => getVolcano().auth.signInWithGoogle()}>
      Sign in with Google
    </button>
  );
}

// app/auth/callback/page.tsx
'use client';
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { getVolcano } from '@/lib/volcano';

export default function AuthCallbackPage() {
  const router = useRouter();
  useEffect(() => {
    getVolcano().initialize().then(({ user }) => {
      router.push(user ? '/dashboard' : '/login?error=auth_failed');
    });
  }, [router]);
  return <div>Completing sign in...</div>;
}

SSR Safety

volcano.auth.signInWith* (OAuth) only works in browser; calling it server-side throws.
The SDK rejects service keys (sk-...) in browser environments.
Use isBrowser() / isServer() from middleware helpers when branching.

Best Practices

Single client instance via getVolcano(). Don't new VolcanoAuth(...) in components.
Loading state is a first-class case — don't render protected UI before useAuth().loading === false.
Pair connect() with disconnect() for realtime in useEffect cleanup.
Validate tokens server-side — do not trust client-supplied user state in API routes / actions.
Use NEXT_PUBLIC_ only for non-secrets; service keys never get this prefix.

Verification Checklist

Client/server responsibilities are clear and correct.
Middleware uses withAuth (or equivalent) before allowing protected routes.
Server components fetch via API routes / server actions / middleware data — never call browser SDK methods directly.
Imports, env vars, dependencies, and init order are consistent.
Realtime is wrapped in a Client Component with proper cleanup.

volcano-nextjs

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills

Volcano Next.js Skill

Role

Workflow

Environment Contract

Execution Environments

Shared Client Pattern (lib/volcano.ts)

AuthContext Provider (Client Component)

Protected Page (Client Component)

Middleware (Edge auth checks)

Middleware Helpers API

API Routes — App Router (Route Handlers)

API Routes — Pages Router

Cookie Sync — required for Server Actions and middleware token reads

Server Components & Server Actions

Server Action template

Realtime in Next.js (Client Component required)

Default Signup & Login Pages

OAuth in Next.js

SSR Safety

Best Practices

Verification Checklist

Optional Fallback References

Volcano Next.js Skill

Role

Workflow

Environment Contract

Execution Environments

Shared Client Pattern (lib/volcano.ts)

AuthContext Provider (Client Component)

Protected Page (Client Component)

Middleware (Edge auth checks)

Middleware Helpers API

API Routes — App Router (Route Handlers)

API Routes — Pages Router

Cookie Sync — required for Server Actions and middleware token reads

Server Components & Server Actions

Server Action template

Realtime in Next.js (Client Component required)

Default Signup & Login Pages

OAuth in Next.js

SSR Safety

Best Practices

Verification Checklist

Optional Fallback References