Skip to main content
The StackClientApp class provides client-side authentication capabilities for JavaScript applications.

​
Constructor

import { StackClientApp } from '@stackframe/js';

const stackApp = new StackClientApp({
  projectId: 'your_project_id',
  publishableClientKey: 'your_publishable_key',
  tokenStore: 'cookie',
  urls: {
    signIn: '/auth/signin',
    signUp: '/auth/signup',
    afterSignIn: '/dashboard',
  },
});

​
Constructor Options

​
projectId
string
Your Stack Auth project ID. Defaults to environment variable based on your framework:
  • Vite: VITE_STACK_PROJECT_ID
  • Create React App: REACT_APP_STACK_PROJECT_ID
  • Next.js: NEXT_PUBLIC_STACK_PROJECT_ID
​
publishableClientKey
string
Your publishable client key. Defaults to environment variable:
  • Vite: VITE_STACK_PUBLISHABLE_CLIENT_KEY
  • Create React App: REACT_APP_STACK_PUBLISHABLE_CLIENT_KEY
  • Next.js: NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY
​
tokenStore
string
required
Token storage mechanism:
  • 'cookie' - HTTP cookies (recommended)
  • 'localStorage' - Browser local storage
  • 'sessionStorage' - Browser session storage
  • 'memory' - Memory only (lost on refresh)
​
baseUrl
string | object
Stack Auth API base URL. Defaults to https://api.stack-auth.com.Can be a string or an object:
{
  browser: 'https://api.stack-auth.com',
  server: 'https://api.stack-auth.com'
}
​
urls
object
Custom URL configuration for authentication pages.
​
oauthScopesOnSignIn
object
OAuth scopes to request during sign in.
{
  google: ['email', 'profile', 'openid'],
  github: ['read:user', 'user:email'],
}
​
redirectMethod
'redirect' | 'push' | 'replace'
default:"'redirect'"
Navigation method for redirects:
  • 'redirect' - Full page redirect (default)
  • 'push' - Client-side navigation (adds to history)
  • 'replace' - Client-side navigation (replaces history)
​
noAutomaticPrefetch
boolean
default:false
Disable automatic data prefetching. By default, Stack Auth prefetches user data when the app is created. Set to true to disable this behavior.
​
extraRequestHeaders
object
Additional headers to include in all API requests.
{
  'X-Custom-Header': 'value',
}

​
Properties

​
projectId

The configured project ID: 
console.log(stackApp.projectId);
// Output: "your_project_id"

​
version

The SDK version: 
console.log(stackApp.version);
// Output: "2.5.0"

​
urls

Configured authentication URLs: 
console.log(stackApp.urls.signIn);
// Output: "/handler/sign-in"

console.log(stackApp.urls.afterSignIn);
// Output: "/"

​
Token Storage

const stackApp = new StackClientApp({
  tokenStore: 'cookie',
});
Pros:
  • Secure (HttpOnly, SameSite)
  • Works across tabs
  • Persists across sessions
Cons:
  • Requires proper CORS configuration
  • Size limitations

​
Local Storage

const stackApp = new StackClientApp({
  tokenStore: 'localStorage',
});
Pros:
  • Large storage capacity
  • Works across tabs
  • Persists across sessions
Cons:
  • Vulnerable to XSS attacks
  • Not secure by default

​
Session Storage

const stackApp = new StackClientApp({
  tokenStore: 'sessionStorage',
});
Pros:
  • Cleared when tab is closed
  • Isolated per tab
Cons:
  • Lost on tab close
  • Not shared across tabs
  • Vulnerable to XSS attacks

​
Memory Storage

const stackApp = new StackClientApp({
  tokenStore: 'memory',
});
Pros:
  • Most secure (not persisted)
  • No storage limitations
Cons:
  • Lost on page refresh
  • Not shared across tabs
  • Poor user experience

​
URL Configuration Examples

​
Custom Authentication Pages

const stackApp = new StackClientApp({
  tokenStore: 'cookie',
  urls: {
    signIn: '/login',
    signUp: '/register',
    accountSettings: '/profile/settings',
    afterSignIn: '/dashboard',
    afterSignUp: '/welcome',
    afterSignOut: '/goodbye',
  },
});

​
External Authentication Server

const stackApp = new StackClientApp({
  tokenStore: 'cookie',
  urls: {
    signIn: 'https://auth.example.com/signin',
    signUp: 'https://auth.example.com/signup',
  },
});

​
OAuth Scopes

Request additional OAuth scopes: 
const stackApp = new StackClientApp({
  tokenStore: 'cookie',
  oauthScopesOnSignIn: {
    google: ['email', 'profile', 'https://www.googleapis.com/auth/calendar.readonly'],
    github: ['read:user', 'user:email', 'repo'],
    microsoft: ['User.Read', 'Calendars.Read'],
  },
});

​
Custom Base URL

Use a custom API endpoint: 
const stackApp = new StackClientApp({
  tokenStore: 'cookie',
  baseUrl: 'https://api.yourstack.com',
});
Or different URLs for browser and server: 
const stackApp = new StackClientApp({
  tokenStore: 'cookie',
  baseUrl: {
    browser: 'https://api.yourstack.com',
    server: 'http://internal-api.yourstack.local',
  },
});

​
Multiple Instances

Create multiple Stack app instances for different projects: 
const appA = new StackClientApp({
  projectId: 'project-a',
  publishableClientKey: 'key-a',
  tokenStore: 'cookie',
});

const appB = new StackClientApp({
  projectId: 'project-b',
  publishableClientKey: 'key-b',
  tokenStore: 'localStorage',
});

​
Best Practices

Use cookie storage

Cookie storage is the most secure option for web applications.

Set environment variables

Store credentials in environment variables, not in source code.

Configure custom URLs

Customize authentication URLs to match your app’s routing structure.

Request minimal scopes

Only request OAuth scopes that your application actually needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us