@strivacity/sdk-nuxt

Strivacity JavaScript SDK

This repository contains the Strivacity JavaScript SDK - a collection of framework-specific packages and example applications for integrating Strivacity's policy-driven authentication journeys into JavaScript and TypeScript applications.

The SDK uses the OAuth 2.0 PKCE flow and supports redirect, popup, native, and embedded modes.

Repository structure

This is a pnpm monorepo. It contains:

• packages/ - Publishable SDK packages
• apps/ - Example applications for each framework
• tools/ - Internal tools for building and testing the SDK and example apps
• plugins/ - Agent skill that teaches AI coding assistants how to use the SDK (see AI coding assistants)

SDK packages

Example applications

Note: apps/backend is a standalone Express server example implementing the BFF pattern - handling the OAuth 2.0 PKCE flow, managing server-side sessions, and exposing a REST API. It's a backend-only implementation that any of the SPA-only framework SDKs (React, Vue, Preact) can pair with instead of talking to the identity provider directly from the browser. It is not a standalone example application on its own and isn't required by any other app.

AI coding assistants

The strivacity agent skill teaches AI coding assistants how to integrate the @strivacity/sdk-* packages: login, registration and logout, protected routes, all four authentication modes, server-managed sessions, API access tokens, debugging, and upgrading from v3.

Claude Code

/plugin marketplace add Strivacity/sdk-js
/plugin install strivacity@strivacity

Cursor: add this repository as a plugin marketplace.

Codex: add this repository as a plugin marketplace (.agents/plugins/marketplace.json).

Other agents: copy plugins/strivacity/skills/strivacity/ into the agent's skills directory.

See the plugin README for details.

Prerequisites

• Node.js LTS
• pnpm 12+

Setup

Clone the repository and install dependencies:

git clone https://github.com/Strivacity/sdk-js.git
cd sdk-js
pnpm install

Environment configuration

Before running any example application, create a .env.local file in the repository root by copying .env.local.example and filling in your values:

cp .env.local.example .env.local

Next.js and Nuxt re-expose some of these variables without the VITE_ prefix (e.g. ISSUER in Next.js, LOGIN_HINT and AUDIENCES in both) through next.config.ts and nuxt.config.ts (runtimeConfig.public).

Building SDK packages

pnpm build

Running example applications

pnpm app:angular:serve       # Angular
pnpm app:next:serve          # Next.js
pnpm app:nuxt:serve          # Nuxt
pnpm app:preact:serve        # Preact
pnpm app:react:serve         # React
pnpm app:solidstart:serve    # Solidstart
pnpm app:sveltekit:serve     # SvelteKit
pnpm app:vue:serve           # Vue.js
pnpm app:backend:serve       # Express backend (BFF)

pnpm app:react-backend:serve   # React + Express backend (BFF)
pnpm app:preact-backend:serve  # Preact + Express backend (BFF)
pnpm app:vue-backend:serve     # Vue.js + Express backend (BFF)

Using the backend app with SPA apps

backend application is a standalone Express server that any of the SPA-only example apps (apps/vue, apps/react, apps/preact) can pair with to run in BFF mode instead of talking to the identity provider directly from the browser. This is worth doing because it keeps tokens out of the browser entirely - they're stored in an encrypted, http-only cookie on the server.

BFF mode is disabled by default in all three apps - set VITE_SERVER_SESSION_URI="/auth/login" in .env.local to enable it.

To try it, run the backend alongside the SPA app you want to pair it with:

pnpm app:backend:serve   # Express backend (BFF) - http://localhost:3000
pnpm app:vue:serve       # or app:react:serve / app:preact:serve - http://localhost:4200

Once enabled:

• Login/Register navigate the browser straight to the backend's /auth/login (handled by the SDK itself via the serverSessionUri option)
• The Callback, Logout, and Revoke pages check sdk.options.serverSessionUri and forward the browser to the backend's /auth/callback, /auth/logout, and /auth/revoke routes instead of calling the client SDK's handleCallback(), logout(), and revoke()
• Before rendering (and before any route guard runs), the app fetches the backend's /auth/session endpoint (with credentials: 'include') and loads the result into the client SDK (sdk.updateSession() in Vue.js, the session prop of StyAuthProvider in React and Preact) to learn whether the user is authenticated and read the decoded ID token claims. Tokens are kept server-side in an http-only cookie and are never written to client-side storage, but for demo purposes /auth/session returns the full session (including the raw tokens) to the SPA - in production, return only what the UI needs
• Token refresh is owned by the backend: /auth/session refreshes an expired access token itself and updates the cookie, and the Profile page's refresh button navigates to /auth/refresh?returnTo=/profile. The client SDK never refreshes tokens on its own in this mode (autoRefresh is ignored when serverSessionUri is set), since that would rotate the refresh token and leave the server's cookie stale

See Server-side session management for the underlying SDK option, and apps/backend for the server-side implementation.

Running example applications with Docker

A single Dockerfile in the repository root can run any of the example apps. Build it once:

docker build -t sdk-js-apps .

Then select an app with $APP and pass its configuration as plain -e flags - the same variables as .env.local.example (see Environment configuration and the apps README for the full list):

docker run --rm -p 4200:4200 \
  -e APP=react \
  -e VITE_MODE=redirect \
  -e VITE_ISSUER=https://your-tenant.strivacity.com \
  -e VITE_CLIENT_ID=your-client-id \
  -e VITE_SCOPES="openid email" \
  -e VITE_REDIRECT_URI=http://localhost:4200/callback \
  sdk-js-apps

$APP is one of: angular, backend, next, nuxt, preact, react, solidstart, sveltekit, vue, preact-backend, react-backend, vue-backend.

Terminology

SPA (Single-Page Application)

A Single-Page Application loads a single HTML page and updates its content dynamically in the browser via JavaScript, without full page reloads when navigating between views. Routing and rendering happen entirely client-side, after the initial page load.

In the Strivacity SDKs: the framework-specific wrappers built for SPA-only frameworks (React, Vue, Preact) run the SDK entirely in the browser (see CSR) - there's no server-side rendering step to integrate with.

CSR (Client-Side Rendering)

Client-Side Rendering is the rendering model where the browser downloads a minimal HTML shell and a JavaScript bundle, then renders and updates the UI in the browser. This is how SPAs work by default, and meta-frameworks (Next.js, Nuxt, SvelteKit, SolidStart) can also render individual routes this way when configured for client-only rendering.

In the Strivacity SDKs: in CSR setups, the SDK's Client SDK runs directly in the browser, storing tokens in client-side storage (localStorage by default) and talking to the identity provider directly - see Client SDK.

SSR (Server-Side Rendering)

Server-Side Rendering is the rendering model where HTML is generated on the server for each request and sent to the browser already populated, then hydrated with JavaScript on the client. This lets a page know the user's authentication state before any client-side JavaScript runs.

In the Strivacity SDKs: in SSR setups, the SDK's Server SDK runs on the server, manages the session (typically in an encrypted http-only cookie), and can hand the decoded claims down to server-rendered components - see Server SDK.

Dynamic rendering

Dynamic rendering is the term some meta-frameworks (notably Next.js's App Router) use for routes that are rendered on the server per request, rather than pre-rendered at build time (static generation). For the purposes of these SDKs it's functionally equivalent to SSR, and the terms are used interchangeably in the framework-specific SDK READMEs where a framework distinguishes rendering strategies at the route level.

BFF (Backend-For-Frontend)

A Backend-For-Frontend is a server-side layer that sits between your client application (the browser) and the identity provider (IDP), and optionally your other backend APIs. Instead of the browser talking to the IDP directly and holding tokens itself, the BFF:

• Initiates and completes the OAuth2/OIDC flow on behalf of the browser
• Stores tokens server-side (e.g. in an encrypted, http-only cookie or a database), so raw tokens never reach client-side JavaScript
• Optionally proxies authenticated API calls, attaching the access token itself before forwarding the request

In the Strivacity SDKs: @strivacity/sdk-core ships a server-side implementation of the BFF pattern - it handles the OAuth2/PKCE flow, session storage, token refresh, and (optionally) back-channel logout on your server. Every framework-specific wrapper builds its own server integration on top of it. See the Server SDK and Server-side session management sections of the core SDK README for details.

Contributing

Please see the contributing guide.

Vulnerability Reporting

See the Guidelines for responsible disclosure for reporting security issues. Please do not report security vulnerabilities on the public issue tracker.

License

Available under the MIT License. See the LICENSE file for details.