User Utils

npm

@stacknet/userutils is the authentication and session package for Stacknet. It provides everything you need to connect users to your Stack, Login, session management, and billing hooks.

PromptMe

Copy the prompt for your framework and give it to your AI coding agent (Claude Code, Cursor, Copilot, etc.) to scaffold Stacknet authentication into your app. Replace stk_REPLACE_ME with your Stack ID.

Next.js


## Task
 
Integrate Stacknet authentication into this Next.js app using `@stacknet/userutils`. The app should let users log in with wallet or OAuth, persist sessions via cookies, and protect pages behind an auth gate.
 
## Stack details
 
- Stack ID: `stk_REPLACE_ME`
- Stacknet URL: `https://stacknet.magma-rpc.com`
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/userutils
```
 
### 2. Environment variables
 
Add to `.env.local`:
 
```
NEXT_PUBLIC_STACK_ID=stk_REPLACE_ME
NEXT_PUBLIC_STACKNET_URL=https://stacknet.magma-rpc.com
AUTH_SECRET=generate-a-random-32-char-string
STACKNET_JWT_SECRET=generate-another-random-32-char-string
```
 
### 3. Create API routes
 
Create these three Next.js App Router API routes:
 
**`app/api/auth/callback/route.ts`**
```ts
import { createAuthCallback } from '@stacknet/userutils/server'
 
const handler = createAuthCallback({
  authSecret: process.env.AUTH_SECRET || '',
  stacknetUrl: process.env.NEXT_PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  stackId: process.env.NEXT_PUBLIC_STACK_ID || '',
  stacknetJwtSecret: process.env.STACKNET_JWT_SECRET,
  secureCookies: process.env.NODE_ENV === 'production',
  sessionMaxAge: 2592000,
  jwtExpiry: 86400,
})
 
export const POST = handler
```
 
**`app/api/auth/session/route.ts`**
```ts
import { createSessionHandler } from '@stacknet/userutils/server'
 
const handler = createSessionHandler({
  authSecret: process.env.AUTH_SECRET || '',
  secureCookies: process.env.NODE_ENV === 'production',
})
 
export async function GET(request: Request) {
  return handler(request)
}
```
 
**`app/api/auth/logout/route.ts`**
```ts
import { createLogoutHandler } from '@stacknet/userutils/server'
 
const handler = createLogoutHandler({
  stacknetUrl: process.env.NEXT_PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  secureCookies: process.env.NODE_ENV === 'production',
})
 
export async function POST(request: Request) {
  return handler(request)
}
```
 
### 4. Create auth provider
 
Create `components/auth-provider.tsx`:
 
```tsx
'use client'
 
import { createContext, useContext, ReactNode } from 'react'
import { UserUtilsProvider, ConnectWidget } from '@stacknet/userutils/components'
import { useSession, useStackAuth } from '@stacknet/userutils/hooks'
import type { UserUtilsConfig, PublicSession } from '@stacknet/userutils'
 
const STACKNET_CONFIG: UserUtilsConfig = {
  apiBaseUrl: '',
  stackId: process.env.NEXT_PUBLIC_STACK_ID || '',
  stacknetUrl: process.env.NEXT_PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  theme: 'dark',
}
 
interface AuthContextValue {
  session: PublicSession | null
  isAuthenticated: boolean
  loading: boolean
  logout: () => Promise<void>
  refresh: () => Promise<unknown>
  config: UserUtilsConfig
}
 
const AuthContext = createContext<AuthContextValue>({
  session: null,
  isAuthenticated: false,
  loading: true,
  logout: async () => {},
  refresh: async () => {},
  config: STACKNET_CONFIG,
})
 
export function useAuth() {
  return useContext(AuthContext)
}
 
function AuthInner({ children }: { children: ReactNode }) {
  const { session, isAuthenticated, loading, logout, refresh } = useStackAuth({
    ...STACKNET_CONFIG,
    autoConnect: false,
  })
 
  return (
    <AuthContext.Provider value={{ session, isAuthenticated, loading, logout, refresh, config: STACKNET_CONFIG }}>
      {children}
    </AuthContext.Provider>
  )
}
 
export function AuthProvider({ children }: { children: ReactNode }) {
  return (
    <UserUtilsProvider config={STACKNET_CONFIG}>
      <AuthInner>{children}</AuthInner>
    </UserUtilsProvider>
  )
}
 
export function LoginWidget({ onSuccess }: { onSuccess?: () => void }) {
  return <ConnectWidget config={STACKNET_CONFIG} onSuccess={onSuccess} showWallets={['phantom', 'metamask']} />
}
 
export { STACKNET_CONFIG }
```
 
### 5. Wrap your layout
 
In `app/layout.tsx`, wrap your app with the `AuthProvider`:
 
```tsx
import { AuthProvider } from '../components/auth-provider'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}
```
 
### 6. Create a login page
 
Create `app/login/page.tsx`:
 
```tsx
'use client'
 
import { useEffect } from 'react'
import { ConnectWidget } from '@stacknet/userutils/components'
import { useAuth, STACKNET_CONFIG } from '../../components/auth-provider'
 
export default function LoginPage() {
  const { isAuthenticated } = useAuth()
 
  useEffect(() => {
    if (isAuthenticated) window.location.href = '/'
  }, [isAuthenticated])
 
  if (isAuthenticated) return null
 
  return (
    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh' }}>
      <ConnectWidget
        config={STACKNET_CONFIG}
        onSuccess={() => { window.location.href = '/' }}
        showWallets={['phantom', 'metamask']}
      />
    </div>
  )
}
```
 
### 7. Protect pages with auth
 
Use the `useAuth` hook to gate content:
 
```tsx
'use client'
 
import { useAuth } from '../components/auth-provider'
 
export default function Dashboard() {
  const { session, isAuthenticated, loading } = useAuth()
 
  if (loading) return <p>Loading...</p>
  if (!isAuthenticated) {
    window.location.href = '/login'
    return null
  }
 
  return <h1>Welcome, {session?.address}</h1>
}
```
 
## Style guidelines
 
Follow the Stacknet visual language:
 
- **Background**: `#191919` (page), `#262625` (cards/panels)
- **Text**: `#FAFAF7` (primary), `#91918D` (secondary), `#666663` (muted)
- **Accent**: `#165DFC` (blue, links and primary actions)
- **Danger**: `#BF4D43` (destructive actions)
- **Borders**: `#40403E`
- **Font**: `'Courier New', monospace` for headings and code; system sans-serif for body text
- **Theme**: always dark — set `theme: 'dark'` in `UserUtilsConfig`
 
## Result
 
After completing these steps you will have:
- Wallet + OAuth login via Stacknet
- Server-side session cookies (30-day max age, 24h JWT rotation)
- A reusable `useAuth()` hook for reading session state anywhere
- A login page with the `ConnectWidget`
- Auth-gated pages that redirect unauthenticated users

Vite (React)


## Task
 
Integrate Stacknet authentication into this Vite + React app using `@stacknet/userutils`. The app should let users log in with wallet or OAuth, manage sessions via a lightweight Express/Hono proxy, and protect routes behind an auth gate.
 
## Stack details
 
- Stack ID: `stk_REPLACE_ME`
- Stacknet URL: `https://stacknet.magma-rpc.com`
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/userutils
```
 
### 2. Environment variables
 
Add to `.env`:
 
```
VITE_STACK_ID=stk_REPLACE_ME
VITE_STACKNET_URL=https://stacknet.magma-rpc.com
VITE_API_BASE_URL=http://localhost:3001
```
 
For the backend proxy (see step 3), add to `.env` on your server:
 
```
STACK_ID=stk_REPLACE_ME
STACKNET_URL=https://stacknet.magma-rpc.com
AUTH_SECRET=generate-a-random-32-char-string
STACKNET_JWT_SECRET=generate-another-random-32-char-string
```
 
### 3. Create auth proxy server
 
Vite has no server-side API routes. Create a small Express server at `server/auth.ts` to proxy the three auth endpoints to Stacknet:
 
```ts
import express from 'express'
import cors from 'cors'
import { createAuthCallback, createSessionHandler, createLogoutHandler } from '@stacknet/userutils/server'
 
const app = express()
app.use(cors({ origin: 'http://localhost:5173', credentials: true }))
app.use(express.json())
 
const callbackHandler = createAuthCallback({
  authSecret: process.env.AUTH_SECRET || '',
  stacknetUrl: process.env.STACKNET_URL || 'https://stacknet.magma-rpc.com',
  stackId: process.env.STACK_ID || '',
  stacknetJwtSecret: process.env.STACKNET_JWT_SECRET,
  secureCookies: process.env.NODE_ENV === 'production',
  sessionMaxAge: 2592000,
  jwtExpiry: 86400,
})
 
const sessionHandler = createSessionHandler({
  authSecret: process.env.AUTH_SECRET || '',
  secureCookies: process.env.NODE_ENV === 'production',
})
 
const logoutHandler = createLogoutHandler({
  stacknetUrl: process.env.STACKNET_URL || 'https://stacknet.magma-rpc.com',
  secureCookies: process.env.NODE_ENV === 'production',
})
 
app.post('/api/auth/callback', (req, res) => callbackHandler(req).then(r => res.status(r.status).json(r.body)))
app.get('/api/auth/session', (req, res) => sessionHandler(req).then(r => res.status(r.status).json(r.body)))
app.post('/api/auth/logout', (req, res) => logoutHandler(req).then(r => res.status(r.status).json(r.body)))
 
app.listen(3001, () => console.log('Auth proxy on :3001'))
```
 
### 4. Create auth provider
 
Create `src/auth-provider.tsx`:
 
```tsx
import { createContext, useContext, ReactNode } from 'react'
import { UserUtilsProvider, ConnectWidget } from '@stacknet/userutils/components'
import { useStackAuth } from '@stacknet/userutils/hooks'
import type { UserUtilsConfig, PublicSession } from '@stacknet/userutils'
 
const STACKNET_CONFIG: UserUtilsConfig = {
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL || 'http://localhost:3001',
  stackId: import.meta.env.VITE_STACK_ID || '',
  stacknetUrl: import.meta.env.VITE_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  theme: 'dark',
}
 
interface AuthContextValue {
  session: PublicSession | null
  isAuthenticated: boolean
  loading: boolean
  logout: () => Promise<void>
  refresh: () => Promise<unknown>
  config: UserUtilsConfig
}
 
const AuthContext = createContext<AuthContextValue>({
  session: null,
  isAuthenticated: false,
  loading: true,
  logout: async () => {},
  refresh: async () => {},
  config: STACKNET_CONFIG,
})
 
export function useAuth() {
  return useContext(AuthContext)
}
 
function AuthInner({ children }: { children: ReactNode }) {
  const { session, isAuthenticated, loading, logout, refresh } = useStackAuth({
    ...STACKNET_CONFIG,
    autoConnect: false,
  })
 
  return (
    <AuthContext.Provider value={{ session, isAuthenticated, loading, logout, refresh, config: STACKNET_CONFIG }}>
      {children}
    </AuthContext.Provider>
  )
}
 
export function AuthProvider({ children }: { children: ReactNode }) {
  return (
    <UserUtilsProvider config={STACKNET_CONFIG}>
      <AuthInner>{children}</AuthInner>
    </UserUtilsProvider>
  )
}
 
export { STACKNET_CONFIG }
```
 
### 5. Wrap your app
 
In `src/main.tsx`:
 
```tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { AuthProvider } from './auth-provider'
import App from './App'
 
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <AuthProvider>
      <App />
    </AuthProvider>
  </StrictMode>
)
```
 
### 6. Create a login page
 
Create `src/Login.tsx`:
 
```tsx
import { useEffect } from 'react'
import { ConnectWidget } from '@stacknet/userutils/components'
import { useAuth, STACKNET_CONFIG } from './auth-provider'
 
export default function Login() {
  const { isAuthenticated } = useAuth()
 
  useEffect(() => {
    if (isAuthenticated) window.location.href = '/'
  }, [isAuthenticated])
 
  if (isAuthenticated) return null
 
  return (
    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh' }}>
      <ConnectWidget
        config={STACKNET_CONFIG}
        onSuccess={() => { window.location.href = '/' }}
        showWallets={['phantom', 'metamask']}
      />
    </div>
  )
}
```
 
### 7. Protect routes with auth
 
```tsx
import { useAuth } from './auth-provider'
 
export default function Dashboard() {
  const { session, isAuthenticated, loading } = useAuth()
 
  if (loading) return <p>Loading...</p>
  if (!isAuthenticated) {
    window.location.href = '/login'
    return null
  }
 
  return <h1>Welcome, {session?.address}</h1>
}
```
 
## Style guidelines
 
Follow the Stacknet visual language:
 
- **Background**: `#191919` (page), `#262625` (cards/panels)
- **Text**: `#FAFAF7` (primary), `#91918D` (secondary), `#666663` (muted)
- **Accent**: `#165DFC` (blue, links and primary actions)
- **Danger**: `#BF4D43` (destructive actions)
- **Borders**: `#40403E`
- **Font**: `'Courier New', monospace` for headings and code; system sans-serif for body text
- **Theme**: always dark — set `theme: 'dark'` in `UserUtilsConfig`
 
## Result
 
After completing these steps you will have:
- Wallet + OAuth login via Stacknet
- An Express auth proxy forwarding to Stacknet
- A reusable `useAuth()` hook for reading session state anywhere
- A login page with the `ConnectWidget`
- Auth-gated routes that redirect unauthenticated users

SvelteKit


## Task
 
Integrate Stacknet authentication into this SvelteKit app using `@stacknet/userutils`. The app should let users log in with wallet or OAuth, persist sessions via cookies using SvelteKit server routes, and protect pages behind an auth gate.
 
## Stack details
 
- Stack ID: `stk_REPLACE_ME`
- Stacknet URL: `https://stacknet.magma-rpc.com`
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/userutils
```
 
### 2. Environment variables
 
Add to `.env`:
 
```
PUBLIC_STACK_ID=stk_REPLACE_ME
PUBLIC_STACKNET_URL=https://stacknet.magma-rpc.com
AUTH_SECRET=generate-a-random-32-char-string
STACKNET_JWT_SECRET=generate-another-random-32-char-string
```
 
### 3. Create server routes
 
SvelteKit server routes handle the auth lifecycle:
 
**`src/routes/api/auth/callback/+server.ts`**
```ts
import { createAuthCallback } from '@stacknet/userutils/server'
import { env } from '$env/dynamic/private'
import { env as pubEnv } from '$env/dynamic/public'
import type { RequestHandler } from './$types'
 
const handler = createAuthCallback({
  authSecret: env.AUTH_SECRET || '',
  stacknetUrl: pubEnv.PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  stackId: pubEnv.PUBLIC_STACK_ID || '',
  stacknetJwtSecret: env.STACKNET_JWT_SECRET,
  secureCookies: !import.meta.env.DEV,
  sessionMaxAge: 2592000,
  jwtExpiry: 86400,
})
 
export const POST: RequestHandler = async ({ request }) => {
  return handler(request)
}
```
 
**`src/routes/api/auth/session/+server.ts`**
```ts
import { createSessionHandler } from '@stacknet/userutils/server'
import { env } from '$env/dynamic/private'
import type { RequestHandler } from './$types'
 
const handler = createSessionHandler({
  authSecret: env.AUTH_SECRET || '',
  secureCookies: !import.meta.env.DEV,
})
 
export const GET: RequestHandler = async ({ request }) => {
  return handler(request)
}
```
 
**`src/routes/api/auth/logout/+server.ts`**
```ts
import { createLogoutHandler } from '@stacknet/userutils/server'
import { env as pubEnv } from '$env/dynamic/public'
import type { RequestHandler } from './$types'
 
const handler = createLogoutHandler({
  stacknetUrl: pubEnv.PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  secureCookies: !import.meta.env.DEV,
})
 
export const POST: RequestHandler = async ({ request }) => {
  return handler(request)
}
```
 
### 4. Create auth store
 
Create `src/lib/auth.ts` using a Svelte store to wrap the userutils client:
 
```ts
import { writable, derived } from 'svelte/store'
 
interface Session {
  userId: string
  address: string
  expiresAt: string
}
 
const session = writable<Session | null>(null)
const loading = writable(true)
 
export const auth = {
  session,
  loading,
  isAuthenticated: derived(session, ($s) => $s !== null),
 
  async init() {
    loading.set(true)
    try {
      const res = await fetch('/api/auth/session', { credentials: 'include' })
      if (res.ok) {
        const data = await res.json()
        session.set(data.session || null)
      }
    } finally {
      loading.set(false)
    }
  },
 
  async logout() {
    await fetch('/api/auth/logout', { method: 'POST', credentials: 'include' })
    session.set(null)
  },
}
```
 
### 5. Create a login page
 
Create `src/routes/login/+page.svelte`:
 
```svelte
<script lang="ts">
  import { onMount } from 'svelte'
  import { ConnectWidget } from '@stacknet/userutils/components'
  import { auth } from '$lib/auth'
 
  const config = {
    apiBaseUrl: '',
    stackId: import.meta.env.PUBLIC_STACK_ID || '',
    stacknetUrl: import.meta.env.PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
    theme: 'dark' as const,
  }
 
  let isAuthenticated = false
  auth.isAuthenticated.subscribe((v) => (isAuthenticated = v))
 
  onMount(() => {
    if (isAuthenticated) window.location.href = '/'
  })
 
  function onSuccess() {
    window.location.href = '/'
  }
</script>
 
{#if !isAuthenticated}
  <div style="display:flex;align-items:center;justify-content:center;min-height:100vh">
    <ConnectWidget {config} {onSuccess} showWallets={['phantom', 'metamask']} />
  </div>
{/if}
```
 
Note: `ConnectWidget` is a React component. If your SvelteKit app does not use React, render the widget in a web component wrapper or build your own login UI that calls the `/api/auth/callback` endpoint directly.
 
### 6. Initialize auth in layout
 
In `src/routes/+layout.svelte`:
 
```svelte
<script lang="ts">
  import { onMount } from 'svelte'
  import { auth } from '$lib/auth'
 
  onMount(() => auth.init())
</script>
 
<slot />
```
 
### 7. Protect pages
 
Use the auth store in any page:
 
```svelte
<script lang="ts">
  import { auth } from '$lib/auth'
  import { goto } from '$app/navigation'
 
  let session: any = null
  let isAuthenticated = false
  let loading = true
 
  auth.session.subscribe((v) => (session = v))
  auth.isAuthenticated.subscribe((v) => (isAuthenticated = v))
  auth.loading.subscribe((v) => {
    loading = v
    if (!v && !isAuthenticated) goto('/login')
  })
</script>
 
{#if loading}
  <p>Loading...</p>
{:else if isAuthenticated}
  <h1>Welcome, {session?.address}</h1>
{/if}
```
 
## Style guidelines
 
Follow the Stacknet visual language:
 
- **Background**: `#191919` (page), `#262625` (cards/panels)
- **Text**: `#FAFAF7` (primary), `#91918D` (secondary), `#666663` (muted)
- **Accent**: `#165DFC` (blue, links and primary actions)
- **Danger**: `#BF4D43` (destructive actions)
- **Borders**: `#40403E`
- **Font**: `'Courier New', monospace` for headings and code; system sans-serif for body text
- **Theme**: always dark — set `theme: 'dark'` in the config
 
## Result
 
After completing these steps you will have:
- Wallet + OAuth login via Stacknet
- SvelteKit server routes handling auth (cookie-based sessions)
- A reactive `auth` store for reading session state anywhere
- A login page with the `ConnectWidget`
- Auth-gated pages that redirect unauthenticated users

Nuxt


## Task
 
Integrate Stacknet authentication into this Nuxt 3 app using `@stacknet/userutils`. The app should let users log in with wallet or OAuth, persist sessions via cookies using Nuxt server routes, and protect pages with middleware.
 
## Stack details
 
- Stack ID: `stk_REPLACE_ME`
- Stacknet URL: `https://stacknet.magma-rpc.com`
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/userutils
```
 
### 2. Environment variables
 
Add to `.env`:
 
```
NUXT_PUBLIC_STACK_ID=stk_REPLACE_ME
NUXT_PUBLIC_STACKNET_URL=https://stacknet.magma-rpc.com
NUXT_AUTH_SECRET=generate-a-random-32-char-string
NUXT_STACKNET_JWT_SECRET=generate-another-random-32-char-string
```
 
Add the runtime config in `nuxt.config.ts`:
 
```ts
export default defineNuxtConfig({
  runtimeConfig: {
    authSecret: '',
    stacknetJwtSecret: '',
    public: {
      stackId: '',
      stacknetUrl: 'https://stacknet.magma-rpc.com',
    },
  },
})
```
 
### 3. Create server routes
 
Nuxt server routes handle the auth lifecycle:
 
**`server/api/auth/callback.post.ts`**
```ts
import { createAuthCallback } from '@stacknet/userutils/server'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
 
  const handler = createAuthCallback({
    authSecret: config.authSecret,
    stacknetUrl: config.public.stacknetUrl,
    stackId: config.public.stackId,
    stacknetJwtSecret: config.stacknetJwtSecret,
    secureCookies: !import.meta.dev,
    sessionMaxAge: 2592000,
    jwtExpiry: 86400,
  })
 
  const request = toWebRequest(event)
  const response = await handler(request)
  return response
})
```
 
**`server/api/auth/session.get.ts`**
```ts
import { createSessionHandler } from '@stacknet/userutils/server'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
 
  const handler = createSessionHandler({
    authSecret: config.authSecret,
    secureCookies: !import.meta.dev,
  })
 
  const request = toWebRequest(event)
  return handler(request)
})
```
 
**`server/api/auth/logout.post.ts`**
```ts
import { createLogoutHandler } from '@stacknet/userutils/server'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
 
  const handler = createLogoutHandler({
    stacknetUrl: config.public.stacknetUrl,
    secureCookies: !import.meta.dev,
  })
 
  const request = toWebRequest(event)
  return handler(request)
})
```
 
### 4. Create auth composable
 
Create `composables/useAuth.ts`:
 
```ts
export function useAuth() {
  const session = useState<any | null>('auth-session', () => null)
  const loading = useState('auth-loading', () => true)
  const isAuthenticated = computed(() => session.value !== null)
 
  async function init() {
    loading.value = true
    try {
      const data = await $fetch('/api/auth/session')
      session.value = (data as any)?.session || null
    } catch {
      session.value = null
    } finally {
      loading.value = false
    }
  }
 
  async function logout() {
    await $fetch('/api/auth/logout', { method: 'POST' })
    session.value = null
  }
 
  return { session, loading, isAuthenticated, init, logout }
}
```
 
### 5. Create auth plugin
 
Create `plugins/auth.client.ts` to initialize auth on app load:
 
```ts
export default defineNuxtPlugin(async () => {
  const { init } = useAuth()
  await init()
})
```
 
### 6. Create a login page
 
Create `pages/login.vue`:
 
```vue
<template>
  <div style="display:flex;align-items:center;justify-content:center;min-height:100vh">
    <ClientOnly>
      <ConnectWidget
        :config="stacknetConfig"
        :on-success="onSuccess"
        :show-wallets="['phantom', 'metamask']"
      />
    </ClientOnly>
  </div>
</template>
 
<script setup lang="ts">
import { ConnectWidget } from '@stacknet/userutils/components'
 
const config = useRuntimeConfig()
const { isAuthenticated } = useAuth()
 
const stacknetConfig = {
  apiBaseUrl: '',
  stackId: config.public.stackId,
  stacknetUrl: config.public.stacknetUrl,
  theme: 'dark' as const,
}
 
watch(isAuthenticated, (val) => {
  if (val) navigateTo('/')
})
 
function onSuccess() {
  navigateTo('/')
}
</script>
```
 
Note: `ConnectWidget` is a React component. Use `<ClientOnly>` and a Vue wrapper or build your own login UI that calls the `/api/auth/callback` endpoint directly.
 
### 7. Protect pages with middleware
 
Create `middleware/auth.ts`:
 
```ts
export default defineNuxtRouteMiddleware(() => {
  const { isAuthenticated, loading } = useAuth()
 
  if (!loading.value && !isAuthenticated.value) {
    return navigateTo('/login')
  }
})
```
 
Use it on any page:
 
```vue
<template>
  <h1>Welcome, {{ session?.address }}</h1>
</template>
 
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { session } = useAuth()
</script>
```
 
## Style guidelines
 
Follow the Stacknet visual language:
 
- **Background**: `#191919` (page), `#262625` (cards/panels)
- **Text**: `#FAFAF7` (primary), `#91918D` (secondary), `#666663` (muted)
- **Accent**: `#165DFC` (blue, links and primary actions)
- **Danger**: `#BF4D43` (destructive actions)
- **Borders**: `#40403E`
- **Font**: `'Courier New', monospace` for headings and code; system sans-serif for body text
- **Theme**: always dark — set `theme: 'dark'` in the config
 
## Result
 
After completing these steps you will have:
- Wallet + OAuth login via Stacknet
- Nuxt server routes handling auth (cookie-based sessions)
- A `useAuth()` composable for reading session state anywhere
- A login page with the `ConnectWidget`
- Route middleware that redirects unauthenticated users

Client side

Wrap your app with UserUtilsProvider and use hooks to read auth state:


import { UserUtilsProvider, ConnectWidget } from '@stacknet/userutils/components'
import { useSession, useStackAuth } from '@stacknet/userutils/hooks'
 
function App() {
  return (
    <UserUtilsProvider config={{
      apiBaseUrl: '/api',
      stackId: 'stk_YOUR_STACK_ID',
      stacknetUrl: 'https://stacknet.magma-rpc.com',
      theme: 'dark',
    }}>
      <MyApp />
    </UserUtilsProvider>
  )
}
 
function MyApp() {
  const { session, isAuthenticated } = useSession()
 
  if (!isAuthenticated) return <ConnectWidget config={config} />
  return <p>Welcome, {session.address}</p>
}

Server side (Next.js API routes)

Three route handlers cover the full auth lifecycle:

/api/auth/callback — verifies the signed challenge and sets the session cookie


import { createAuthCallback } from '@stacknet/userutils/server'
 
const handler = createAuthCallback({
  authSecret: process.env.AUTH_SECRET,
  stacknetUrl: process.env.NEXT_PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  stackId: process.env.NEXT_PUBLIC_STACK_ID,
  stacknetJwtSecret: process.env.STACKNET_JWT_SECRET,
  secureCookies: process.env.NODE_ENV === 'production',
  sessionMaxAge: 2592000,  // 30 days
  jwtExpiry: 86400,        // 24 hours
})
 
export const POST = handler

/api/auth/session — returns current session state


import { createSessionHandler } from '@stacknet/userutils/server'
 
const handler = createSessionHandler({
  authSecret: process.env.AUTH_SECRET,
  secureCookies: process.env.NODE_ENV === 'production',
})
 
export async function GET(request: Request) {
  return handler(request)
}

/api/auth/logout — clears the session cookie


import { createLogoutHandler } from '@stacknet/userutils/server'
 
const handler = createLogoutHandler({
  stacknetUrl: process.env.NEXT_PUBLIC_STACKNET_URL || 'https://stacknet.magma-rpc.com',
  secureCookies: process.env.NODE_ENV === 'production',
})
 
export async function POST(request: Request) {
  return handler(request)
}

Hooks reference

Hook	Returns	Description
`useSession`	`{ session, isAuthenticated }`	Read-only session state — user ID, address, expiry
`useStackAuth`	`{ session, wallet, authenticateSolana, authenticateEVM, logout, refresh }`	Full auth control — connect wallets, sign challenges, manage session
`useWeb3Wallet`	`{ connected, address, chain, provider }`	Wallet connection state and provider detection
`useAuthBridge`	`{ ready, known, identity, identityCount, resolvedStackId }`	Cross-domain SSO — detects identities across Stacks
`usePlans`	`{ plans, loading }`	List billing plans available on the Stack
`useSubscription`	`{ subscription, active, plan }`	Current user subscription state
`useUsage`	`{ usage, remaining, limit }`	Token usage against current plan
`useBillingHistory`	`{ records, loading }`	Past billing and payment records
`usePrepaidCheckout`	`{ checkout, processing }`	Initiate credit purchases

Components reference

Component	Props	Description
`UserUtilsProvider`	`config: UserUtilsConfig`	Required context provider — wrap your app root
`ConnectWidget`	`config, onSuccess, showWallets, showOTP, title`	Drop-in login UI with wallet and OAuth options

Environment variables

Variable	Required	Description
`NEXT_PUBLIC_STACK_ID`	Yes	Your Stack ID (e.g. `stk_abc123`)
`NEXT_PUBLIC_STACKNET_URL`	Yes	Stacknet backend URL (`https://stacknet.magma-rpc.com`)
`AUTH_SECRET`	Yes	Secret for signing session cookies (min 32 chars)
`STACKNET_JWT_SECRET`	Yes	Secret for re-signing JWTs to Stacknet backend

Cross-domain SSO

The useAuthBridge hook enables single sign-on across multiple Stacks. When a user is already authenticated on one Stack, the bridge detects their identity and can resolve which Stack they last used:


import { useAuthBridge } from '@stacknet/userutils/hooks'
 
function LoginPage() {
  const bridge = useAuthBridge()
 
  if (bridge.ready && bridge.known) {
    return <p>Welcome back — {bridge.identity.address}</p>
  }
 
  return <ConnectWidget config={config} />
}