workos-convex-sveltekit

This library is designed to augment WorkOS AuthKit + Convex with built in user management functionality. It provides wrappers for some convex-svelte and @workos/authkit-sveltekit functions that keep the convex users database in sync with user data from AuthKit

Installation

Be sure to follow all the steps in the installation guide, see referenced documenation for more information. The guide assumes you have a new or existing sveltekit project and that all commands are run from within that project directory.

Install npm package

Convex and AuthKit dependencies:

npm install -S convex convex-svelte @workos-inc/node @workos/authkit-sveltekit

This package:

npm install workos-convex-sveltekit

Configure project

Follow the steps below from the Convex & WorkOS AuthKit documentation:

Configure WorkOS account (adapted from Convex docs):

• Sign up for an account at: https://signin.workos.com/sign-up
• Enable AuthKit on your account
• Add callback endpoint during setup: https://<domain>/api/auth/callback
• Copy Client and API keys
• Enable CORS for your domain (eg. https://localhost:5173 for development) in the WorkOS Dashboard
• Set up custom JWT template. Navigate to WorkOS Dashboard > Authentication > Sessions and add the folowing custom JWT template:

   {
     "aud": "<your_workos_client_id>",
     "user_id": {{user.id}},
     "email": {{user.email}},
     "first_name": {{user.first_name}},
     "last_name": {{user.last_name}},
     "name": "{{user.first_name}} {{user.last_name}}",
     "email_verified": {{user.email_verified}},
     "org_id": {{organization.id}},
     "org_name": {{organization.name}},
     "org_role": {{organization_membership.role}}
   }
  

  NOTE We have to supply the workos client id here in the JWT response manually because the convex library expects our JWT to have the "aud" claim, which is not included by WorkOS by default.

Configure environment variables:

Create .env.local with the following contents in the project root:

# WorkOS AuthKit Configuration
WORKOS_CLIENT_ID=<client_id>
WORKOS_API_KEY=<api_key>
WORKOS_REDIRECT_URI=http://localhost:5173/api/auth/callback
WORKOS_COOKIE_PASSWORD=<cookie_password>
#
# Convex (public) URL
PUBLIC_CONVEX_URL=<public_convex_url>

NOTE To generate a secure cookie password use: openssl rand -base64 24 NOTE Remember to add .env.local to your .gitignore

Copy template files

The library provides a CLI that automatically copies necessary files to your project. These files provide all the boilerplate needed for a basic Convex + WorkOS SvelteKit auth integration. If you are implementing into an existing project, you may need to manually merge the files.

• src/convex/auth.config.ts: Default authentication configuration for convex. Copied directly from the Convex Documentation
• src/convex/users.ts - Convex user query functions
• src/convex/schema.ts - Convex schema file
• src/routes/api/auth/callback/+server.ts - Handles the auth callback
• src/routes/api/auth/logout/+server.ts - Handles logging the user out
• src/routes/api/auth/token/+server.ts - Returns a JWT token for the currently authenticated user
• src/routes/+layout.svelte - Base layout file that configures auth on the client
• src/routes/admin/+layout.server.ts - Example of how to use the authenticatedRoute to protect a specific route
• src/hooks.server.ts - SvelteKit server hooks to handle configuring auth
• src/app.d.ts - Extended global types for SvelteKit
• convex.json - Configure the convex directory to be inside src

You can inspect and modify these files as needed after copying. All files preserve your existing code if conflicts are found - interactive diff and prompt are shown before any overwrite.

npx workos-convex-sveltekit copy

See CLI Options for more details about the CLI tool.

Configure convex deployment

You'll need to create a new convex deployment and configure it. Run the npx convex dev command and follow the prompts to either create or use and existing project. Then follow the steps to configure the WORKOS_CLIENT_ID in the convex dashboard.

On successful authentication, the library uses ConvexHttpClient and calls api.users.store to upsert the current user in your users table. Existing roles are preserved; new users start with roles: [].

Optional configurations

TODO: This section will outline some additional configurations that can be made in the WorkOS UI, and how to integrate them with this library.

Usage

Once you have all the Configuration steps completed, you're ready to start using the library.

Schema helpers usage

// src/convex/schema.ts
import { defineSchema } from 'convex/server';
import { v } from 'convex/values';
import { defaultUsers, extendUsers } from 'workos-convex-sveltekit/schema';

export default defineSchema({
  users: defaultUsers(v)
});

// Or extend with custom fields (+ you can chain your own indexes)
// users: extendUsers(v, { extraField: v.string() })
//   .index('by_extra_field', ['extraField'])

Notes:

• The helpers already apply indexes by_email and by_workos_user_id.
• No generics are required.

Library exports

// Server utilities
import {
  configureServerAuth,
  authenticatedRequest,
  handleToken,
  handleSignOut,
  handleSignIn,
} from 'workos-convex-sveltekit';

// Client utility
import { configureClientAuth } from 'workos-convex-sveltekit';

// Schema helpers
import { defaultUsers, extendUsers } from 'workos-convex-sveltekit/schema';

Client setup (+layout.svelte)

<script lang="ts">
  import { browser } from '$app/environment';
  import { setupConvex, useConvexClient } from 'convex-svelte';
  import { configureClientAuth } from 'workos-convex-sveltekit';
  import { PUBLIC_CONVEX_URL } from '$env/static/public';

  configureClientAuth(setupConvex, useConvexClient, browser, PUBLIC_CONVEX_URL as string);
  let { children } = $props();
</script>

{@render children?.()}

Authenticating server routes

You can authenticate a server route using the authenticatedRequest function in any +layout.server.ts file:

import type { LayoutServerLoad } from './$types';
import { authenticatedRequest } from 'workos-convex-sveltekit';
import { authKit } from '@workos/authkit-sveltekit';

export const load: LayoutServerLoad = authenticatedRequest(authKit, async ({ auth, url, locals }) => {
    const user = auth.user;

    //User is authenticated here

    return {
        user: user
    };
});

Auth routes provided by the template

• GET /api/auth/callback (WorkOS callback)
• GET /api/auth/token (returns JWT via handleToken)
• GET /api/auth/logout (signs out via handleSignOut)
• GET /api/auth/signin (optional; via handleSignIn)

Optional: Sign‑in route

// src/routes/api/auth/signin/+server.ts
import { authKit } from '@workos/authkit-sveltekit';
import { handleSignIn } from 'workos-convex-sveltekit';

export const GET = handleSignIn(authKit);

Using queries in pages

In any +page.svelte, you can access the useQuery() or convex.mutation() functions in your svelte app. The template provides user queries in src/convex/users.ts:

• store (mutation): upserts the current user on sign-in; preserves existing roles; initializes roles: [] for new users; updates lastSignInAt and timestamps.
• getCurrentUser (query): returns the current authenticated user or null.
• getUserById (query): looks up a user by workosUserId.
• getUserByEmail (query): looks up a user by email.
• getAllUsers (query): returns all users.
• hasRole (query): returns true/false if the current user has the provided role. ```svelte
  {#if queryResult.isLoading}

  Loading...

  {:else if queryResult.error}

  Error: {queryResult.error.message}

  {:else if !queryResult.data || queryResult.data.length === 0}

  No data here!

  {:else} {#each queryResult.data as item, index}

  item

  {/each} {/if}

  <!-- Perform mutation -->
  <form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }} class="form">
      <input
          type="text"
          bind:value={textInput}
          placeholder="Enter some text..."
      />
      <button type="submit">
          Add Public Data
      </button>
  </form>
  

  ```

  Role check example

  <script lang="ts">
    import { useQuery } from 'convex-svelte';
    import { api } from '../convex/_generated/api';
  
    const isAdmin = useQuery(api.users.hasRole, { role: 'admin' });
  </script>
  

  Server actions

  You can also use SvelteKits server actions

  import { authenticatedRequest } from "workos-convex-sveltekit";
  import { authKit } from "@workos/authkit-sveltekit";
  import { api } from "../../convex/_generated/api.js";
  import { PUBLIC_CONVEX_URL } from "$env/static/public";
  import { ConvexHttpClient } from "convex/browser";
  
  export const actions = {
      privateAction: authenticatedRequest(authKit, async ({auth, request}) => {
          const convex = new ConvexHttpClient(PUBLIC_CONVEX_URL);
          convex.setAuth(auth.accessToken as string);
  
          const result = await convex.query(api.users.getAllUsers, { });
  
          return { data: result };
      })
  };
  

  Best Practices

  These are some best practices that I have come up with

  • Authorization inside your convex query/mutation functions. Limit client side trust as much as possible.

  Deployment

  When deploying besure to include all the WorkOS environment variables for the build.

  CLI Options

  The workos-convex-sveltekit CLI provides several options to control how files are copied and how conflicts are handled. These can be combined as needed. | Option | Alias | Description | Default | |----------------------|---------|----------------------------------------------------------------------------------------------|---------------------------| | --dest <path> | | Destination directory for copied files | Current working directory | | --force | | Overwrite conflicting files without prompting | false | | --yes | -y | Assume "yes" to all prompts (non-interactive). Combine with CI use | false | | --dry-run | | Show planned actions (which files would be created, overwritten, or skipped), but make no changes | false | | --backup | | When overwriting, create backups of existing files | false | | --verbose | -v | Print verbose output, including individual file actions | false | | --help | -h | Show usage help | | | --version | -V | Show CLI version | |

  Example

  npx workos-convex-sveltekit copy --dry-run --verbose
  # or explicitly target the project root
  npx workos-convex-sveltekit copy --dest . --dry-run --verbose
  

  • This will show a summary of all file actions that would be taken, writing nothing.

    Conflict Handling

  • By default, if a destination file already exists and contents differ, you'll be shown a colorized diff and prompted for action (overwrite, skip, backup, overwrite all, skip all).
  • To automate in CI or non-interactive use, use --force or --yes to skip prompts and automatically overwrite conflicting files.
  • Use --backup to always back up existing files before overwriting.

  See the output of:

  npx workos-convex-sveltekit --help
  

  for a full list of options.

  Development

  Planned improvements:

  • Look more into how profile images are handled and how we might allow users to change them and not have them re-written by workos syncing. Or maybe they can be updated through workos directly?
  • Figure out how to get the users queries exported with proper typescript support, to avoid copying them all directly from the template. This will help with handling udpates where changes may be needed to the fucntionality of users queries.
  • Add support for organizations, and role based authorization

  Project Structure

  workos-convex-sveltekit/
  ├── src/
  │   ├── index.ts            # Main library exports
  │   ├── schema.ts           # Schema helpers (exported as subpath)
  │   ├── cli.ts              # CLI tool (exported as command)
  │   └── cli/                # CLI implementation
  │       ├── args.ts
  │       ├── copy.ts
  │       ├── log.ts
  │       ├── paths.ts
  │       └── prompts.ts
  ├── templates/              # Files copied into consuming app
  │   └── src/...
  ├── dist/                   # Build output
  └── package.json
  

  # Build the library
  npm run build
  
  # Clean build artifacts
  npm run clean
  

  Linking locally (dev workflow)

  # In this repo
  npm run build && npm link
  
  # In your consuming app
  npm link --save workos-convex-sveltekit
  workos-convex-sveltekit copy --dry-run --verbose
  

  License

  ISC