convex-workos-skill

Name: convex-workos-skill
Author: PolarCoding85

17stars3forks

How to install convex-workos-skill?

polarcoding85/convex-agent-skillz/convex-workos-skill

$npx -y skills add PolarCoding85/convex-agent-skillz --skill convex-workos-skill

Installs into the current project.

Summary

WorkOS AuthKit authentication integration for Convex. Use when setting up WorkOS AuthKit, configuring ConvexProviderWithAuthKit, handling auto-provisioning, or troubleshooting WorkOS-specific auth issues.

Files · 1

View on GitHub

SKILL.md

1	# Convex + WorkOS AuthKit
2
3	Provider-specific patterns for integrating WorkOS AuthKit with Convex.
4
5	## Required Configuration
6
7	### 1. auth.config.ts
8
9	```typescript
10	// convex/auth.config.ts
11	const clientId = process.env.WORKOS_CLIENT_ID;
12
13	export default {
14	providers: [
15	{
16	type: 'customJwt',
17	issuer: 'https://api.workos.com/',
18	algorithm: 'RS256',
19	applicationID: clientId,
20	jwks: `https://api.workos.com/sso/jwks/${clientId}`
21	},
22	{
23	type: 'customJwt',
24	issuer: `https://api.workos.com/user_management/${clientId}`,
25	algorithm: 'RS256',
26	jwks: `https://api.workos.com/sso/jwks/${clientId}`
27	}
28	]
29	};
30	```
31
32	Note: WorkOS requires TWO provider entries for different JWT issuers.
33
34	### 2. Environment Variables
35
36	```bash
37	# .env.local (Vite/React)
38	VITE_WORKOS_CLIENT_ID=client_01...
39	VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback
40
41	# .env.local (Next.js)
42	WORKOS_CLIENT_ID=client_01...
43	WORKOS_API_KEY=sk_test_...
44	WORKOS_COOKIE_PASSWORD=your_32_char_minimum_password_here
45	NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3000/callback
46
47	# Convex Dashboard Environment Variables
48	WORKOS_CLIENT_ID=client_01...
49	```
50
51	## Client Setup
52
53	### React (Vite)
54
55	```typescript
56	// src/main.tsx
57	import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react";
58	import { ConvexProviderWithAuthKit } from "@convex-dev/workos";
59	import { ConvexReactClient } from "convex/react";
60
61	const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
62
63	ReactDOM.createRoot(document.getElementById("root")!).render(
64	<AuthKitProvider
65	clientId={import.meta.env.VITE_WORKOS_CLIENT_ID}
66	redirectUri={import.meta.env.VITE_WORKOS_REDIRECT_URI}
67	>
68	<ConvexProviderWithAuthKit client={convex} useAuth={useAuth}>
69	<App />
70	</ConvexProviderWithAuthKit>
71	</AuthKitProvider>
72	);
73	```
74
75	Install: `npm install @workos-inc/authkit-react @convex-dev/workos`
76
77	### Next.js App Router
78
79	```typescript
80	// components/ConvexClientProvider.tsx
81	'use client';
82
83	import { ReactNode, useCallback, useRef } from 'react';
84	import { ConvexReactClient, ConvexProviderWithAuth } from 'convex/react';
85	import { AuthKitProvider, useAuth, useAccessToken } from '@workos-inc/authkit-nextjs/components';
86
87	const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
88
89	export function ConvexClientProvider({ children }: { children: ReactNode }) {
90	return (
91	<AuthKitProvider>
92	<ConvexProviderWithAuth client={convex} useAuth={useAuthFromAuthKit}>
93	{children}
94	</ConvexProviderWithAuth>
95	</AuthKitProvider>
96	);
97	}
98
99	function useAuthFromAuthKit() {
100	const { user, loading: isLoading } = useAuth();
101	const { accessToken, loading: tokenLoading, error: tokenError } = useAccessToken();
102
103	const loading = (isLoading ?? false) \|\| (tokenLoading ?? false);
104	const authenticated = !!user && !!accessToken && !loading;
105
106	const stableAccessToken = useRef<string \| null>(null);
107	if (accessToken && !tokenError) {
108	stableAccessToken.current = accessToken;
109	}
110
111	const fetchAccessToken = useCallback(async () => {
112	if (stableAccessToken.current && !tokenError) {
113	return stableAccessToken.current;
114	}
115	return null;
116	}, [tokenError]);
117
118	return {
119	isLoading: loading,
120	isAuthenticated: authenticated,
121	fetchAccessToken,
122	};
123	}
124	```
125
126	Install: `npm install @workos-inc/authkit-nextjs @convex-dev/workos`
127
128	### Next.js Middleware
129
130	```typescript
131	// middleware.ts
132	import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
133
134	export default authkitMiddleware({
135	middlewareAuth: {
136	enabled: true,
137	unauthenticatedPaths: ['/', '/sign-in', '/sign-up']
138	}
139	});
140
141	export const config = {
142	matcher: ['/((?!.\\..\|_next).)', '/', '/(api\|trpc)(.)']
143	};
144	```
145
146	### Next.js Auth Routes
147
148	```typescript
149	// app/callback/route.ts
150	import { handleAuth } from '@workos-inc/authkit-nextjs';
151	export const GET = handleAuth();
152
153	// app/sign-in/route.ts
154	import { redirect } from 'next/navigation';
155	import { getSignInUrl } from '@workos-inc/authkit-nextjs';
156	export async function GET() {
157	return redirect(await getSignInUrl());
158	}
159
160	// app/sign-up/route.ts
161	import { redirect } from 'next/navigation';
162	import { getSignUpUrl } from '@workos-inc/authkit-nextjs';
163	export async function GET() {
164	return redirect(await getSignUpUrl());
165	}
166	```
167
168	## CORS Configuration (React/Vite only)
169
170	For React apps, configure CORS in WorkOS Dashboard:
171
172	1. Authentication > Sessions > Cross-Origin Resource Sharing (CORS)
173	2. Click Manage
174	3. Add your dev domain: `http://localhost:5173`
175	4. Add your prod domain when deploying
176
177	## UI Components
178
179	```typescript
180	import { useAuth } from "@workos-inc/authkit-react"; // or authkit-nextjs/components
181	import { Authenticated, Unauthenticated } from "convex/re

People who liked this also viewed

6 picks

Type

convex-workos-skill

17stars3forks

View on GitHub

How to install convex-workos-skill?

polarcoding85/convex-agent-skillz/convex-workos-skill

$npx -y skills add PolarCoding85/convex-agent-skillz --skill convex-workos-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Convex + WorkOS AuthKit
2
3	Provider-specific patterns for integrating WorkOS AuthKit with Convex.
4
5	## Required Configuration
6
7	### 1. auth.config.ts
8
9	```typescript
10	// convex/auth.config.ts
11	const clientId = process.env.WORKOS_CLIENT_ID;
12
13	export default {
14	providers: [
15	{
16	type: 'customJwt',
17	issuer: 'https://api.workos.com/',
18	algorithm: 'RS256',
19	applicationID: clientId,
20	jwks: `https://api.workos.com/sso/jwks/${clientId}`
21	},
22	{
23	type: 'customJwt',
24	issuer: `https://api.workos.com/user_management/${clientId}`,
25	algorithm: 'RS256',
26	jwks: `https://api.workos.com/sso/jwks/${clientId}`
27	}
28	]
29	};
30	```
31
32	Note: WorkOS requires TWO provider entries for different JWT issuers.
33
34	### 2. Environment Variables
35
36	```bash
37	# .env.local (Vite/React)
38	VITE_WORKOS_CLIENT_ID=client_01...
39	VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback
40
41	# .env.local (Next.js)
42	WORKOS_CLIENT_ID=client_01...
43	WORKOS_API_KEY=sk_test_...
44	WORKOS_COOKIE_PASSWORD=your_32_char_minimum_password_here
45	NEXT_PUBLIC_WORKOS_REDIRECT_URI=http://localhost:3000/callback
46
47	# Convex Dashboard Environment Variables
48	WORKOS_CLIENT_ID=client_01...
49	```
50
51	## Client Setup
52
53	### React (Vite)
54
55	```typescript
56	// src/main.tsx
57	import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react";
58	import { ConvexProviderWithAuthKit } from "@convex-dev/workos";
59	import { ConvexReactClient } from "convex/react";
60
61	const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
62
63	ReactDOM.createRoot(document.getElementById("root")!).render(
64	<AuthKitProvider
65	clientId={import.meta.env.VITE_WORKOS_CLIENT_ID}
66	redirectUri={import.meta.env.VITE_WORKOS_REDIRECT_URI}
67	>
68	<ConvexProviderWithAuthKit client={convex} useAuth={useAuth}>
69	<App />
70	</ConvexProviderWithAuthKit>
71	</AuthKitProvider>
72	);
73	```
74
75	Install: `npm install @workos-inc/authkit-react @convex-dev/workos`
76
77	### Next.js App Router
78
79	```typescript
80	// components/ConvexClientProvider.tsx
81	'use client';
82
83	import { ReactNode, useCallback, useRef } from 'react';
84	import { ConvexReactClient, ConvexProviderWithAuth } from 'convex/react';
85	import { AuthKitProvider, useAuth, useAccessToken } from '@workos-inc/authkit-nextjs/components';
86
87	const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
88
89	export function ConvexClientProvider({ children }: { children: ReactNode }) {
90	return (
91	<AuthKitProvider>
92	<ConvexProviderWithAuth client={convex} useAuth={useAuthFromAuthKit}>
93	{children}
94	</ConvexProviderWithAuth>
95	</AuthKitProvider>
96	);
97	}
98
99	function useAuthFromAuthKit() {
100	const { user, loading: isLoading } = useAuth();
101	const { accessToken, loading: tokenLoading, error: tokenError } = useAccessToken();
102
103	const loading = (isLoading ?? false) \|\| (tokenLoading ?? false);
104	const authenticated = !!user && !!accessToken && !loading;
105
106	const stableAccessToken = useRef<string \| null>(null);
107	if (accessToken && !tokenError) {
108	stableAccessToken.current = accessToken;
109	}
110
111	const fetchAccessToken = useCallback(async () => {
112	if (stableAccessToken.current && !tokenError) {
113	return stableAccessToken.current;
114	}
115	return null;
116	}, [tokenError]);
117
118	return {
119	isLoading: loading,
120	isAuthenticated: authenticated,
121	fetchAccessToken,
122	};
123	}
124	```
125
126	Install: `npm install @workos-inc/authkit-nextjs @convex-dev/workos`
127
128	### Next.js Middleware
129
130	```typescript
131	// middleware.ts
132	import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
133
134	export default authkitMiddleware({
135	middlewareAuth: {
136	enabled: true,
137	unauthenticatedPaths: ['/', '/sign-in', '/sign-up']
138	}
139	});
140
141	export const config = {
142	matcher: ['/((?!.\\..\|_next).)', '/', '/(api\|trpc)(.)']
143	};
144	```
145
146	### Next.js Auth Routes
147
148	```typescript
149	// app/callback/route.ts
150	import { handleAuth } from '@workos-inc/authkit-nextjs';
151	export const GET = handleAuth();
152
153	// app/sign-in/route.ts
154	import { redirect } from 'next/navigation';
155	import { getSignInUrl } from '@workos-inc/authkit-nextjs';
156	export async function GET() {
157	return redirect(await getSignInUrl());
158	}
159
160	// app/sign-up/route.ts
161	import { redirect } from 'next/navigation';
162	import { getSignUpUrl } from '@workos-inc/authkit-nextjs';
163	export async function GET() {
164	return redirect(await getSignUpUrl());
165	}
166	```
167
168	## CORS Configuration (React/Vite only)
169
170	For React apps, configure CORS in WorkOS Dashboard:
171
172	1. Authentication > Sessions > Cross-Origin Resource Sharing (CORS)
173	2. Click Manage
174	3. Add your dev domain: `http://localhost:5173`
175	4. Add your prod domain when deploying
176
177	## UI Components
178
179	```typescript
180	import { useAuth } from "@workos-inc/authkit-react"; // or authkit-nextjs/components
181	import { Authenticated, Unauthenticated } from "convex/re

People who liked this also viewed

6 picks

Type