React provider for seamless Vortex integration with Next.js SDK
npm install @teamvortexsoftware/vortex-react-providerReact provider for seamless Vortex integration with Next.js SDK. This package provides React components and hooks that work in conjunction with the Vortex Next.js SDK to simplify invitation management and JWT authentication in your React applications.
``bash`
npm install @teamvortexsoftware/vortex-react-provideror
pnpm add @teamvortexsoftware/vortex-react-provideror
yarn add @teamvortexsoftware/vortex-react-provider
This package is designed to work with the Vortex Next.js SDK (@teamvortexsoftware/vortex-nextjs-15-sdk).
⚠️ IMPORTANT: Use the createVortexRoutes() helper from the Next.js SDK to ensure perfect path compatibility:
`typescript
// In your Next.js backend setup
import { createVortexRoutes } from '@teamvortexsoftware/vortex-nextjs-15-sdk';
const routes = createVortexRoutes();
// Create the exact file structure shown in the Next.js SDK README
`
This ensures the API paths match exactly what this React provider expects.
`jsx
// app/layout.tsx or pages/_app.tsx
import { VortexProvider } from '@teamvortexsoftware/vortex-react-provider';
export default function RootLayout({ children }) {
return (
$3
`jsx
// components/UserProfile.tsx
import { useVortexAuth } from '@teamvortexsoftware/vortex-react-provider';export function UserProfile() {
const { user, isAuthenticated, isLoading, error } = useVortexAuth();
if (isLoading) return
Loading...;
if (error) return Error: {error.message};
if (!isAuthenticated) return Please log in; return (
Welcome, {user.userId}!
Groups: {user.groups.map(g => g.name).join(', ')}
);
}
``jsx
// components/InvitationManager.tsx
import { useState } from 'react';
import { useInvitations } from '@teamvortexsoftware/vortex-react-provider';export function InvitationManager() {
const [invitations, setInvitations] = useState([]);
const {
getInvitationsByTarget,
revokeInvitation,
isLoading,
getError
} = useInvitations();
const loadInvitations = async () => {
try {
const result = await getInvitationsByTarget('email', 'user@example.com');
setInvitations(result);
} catch (error) {
console.error('Failed to load invitations:', error);
}
};
const handleRevoke = async (invitationId) => {
try {
await revokeInvitation(invitationId);
// Reload invitations
await loadInvitations();
} catch (error) {
console.error('Failed to revoke invitation:', error);
}
};
return (
{invitations.map(invitation => (
{invitation.status}
onClick={() => handleRevoke(invitation.id)}
disabled={isLoading(revoke-${invitation.id})}
>
Revoke
))}
);
}
`API Reference
$3
Main provider component that manages authentication state and API communication.
Props:
-
children: React.ReactNode - Child components
- config?: VortexConfig - Optional configuration objectConfiguration Options:
-
apiBaseUrl?: string - Base URL for API calls (default: '/api/vortex')
- refreshJwtInterval?: number - JWT refresh interval in milliseconds (default: 30 minutes)
- defaultGroups?: InvitationGroup[] - Default groups for new users
- onError?: (error: Error) => void - Error callback
- onJwtRefresh?: (jwt: string) => void - JWT refresh callback$3
#### useVortex()
Main hook providing access to all functionality.
Returns: Full VortexContextValue
#### useVortexAuth()
Hook focused on authentication state.
Returns:
-
jwt: string | null - Current JWT token
- user: AuthenticatedUser | null - Current user data
- isAuthenticated: boolean - Authentication status
- isLoading: boolean - Loading state
- error: Error | null - Current error
- refreshJwt: () => Promise - Refresh JWT manually
- clearAuth: () => void - Clear authentication data#### useVortexJWT()
Hook for JWT-specific utilities.
Returns:
- All authentication state from useVortexAuth
-
isExpiringSoon: (bufferMinutes?: number) => boolean - Check if JWT is expiring
- refreshIfNeeded: (bufferMinutes?: number) => Promise - Refresh if expiring soon#### useInvitations()
Hook for invitation management with built-in loading states.
Returns:
-
loading: Record - Loading states by operation
- errors: Record - Error states by operation
- isAuthenticated: boolean - Authentication status
- getInvitationsByTarget: (targetType, targetValue) => Promise
- getInvitation: (invitationId) => Promise
- revokeInvitation: (invitationId) => Promise
- acceptInvitations: (invitationIds, target) => Promise
- getInvitationsByGroup: (groupType, groupId) => Promise
- deleteInvitationsByGroup: (groupType, groupId) => Promise
- reinvite: (invitationId) => Promise
- isLoading: (key) => boolean - Check loading state for specific operation
- getError: (key) => Error | null - Get error for specific operation
- clearError: (key) => void - Clear error for specific operationTypes
The package exports all necessary TypeScript types:
`typescript
import type {
VortexConfig,
VortexContextValue,
VortexProviderProps,
AuthenticatedUser,
InvitationTarget,
InvitationResult,
InvitationGroup,
ApiResponse,
} from '@teamvortexsoftware/vortex-react-provider';
`Integration with Vortex Invite Component
This provider works seamlessly with the existing VortexInvite component:
`jsx
// components/InvitePage.tsx
import { VortexInvite } from '@teamvortexsoftware/vortex-react';
import { useVortexAuth } from '@teamvortexsoftware/vortex-react-provider';export function InvitePage() {
const { isAuthenticated, user } = useVortexAuth();
return (
{isAuthenticated ? (
// The VortexInvite component can now access authentication
// state from the provider context automatically
/>
) : (
Please authenticate to send invitations
)}
);
}
`Error Handling
The provider includes comprehensive error handling:
`jsx
import { useVortex } from '@teamvortexsoftware/vortex-react-provider';function MyComponent() {
const { error } = useVortex();
if (error) {
return
Application Error: {error.message};
} // Component logic
}
`For invitation-specific errors:
`jsx
import { useInvitations } from '@teamvortexsoftware/vortex-react-provider';function InvitationComponent() {
const { getError, clearError } = useInvitations();
const invitationError = getError('revoke-invitation-123');
return (
{invitationError && (
{invitationError.message}
)}
);
}
``- JWT tokens are automatically managed and refreshed
- All API calls go through the configured backend routes
- Access control is handled by your Next.js SDK configuration
- Tokens are not persisted between browser sessions for security
This package follows the security principles established by the Vortex Next.js SDK:
1. Server-side authentication: JWT generation happens server-side only
2. Access control: All invitation operations respect your configured access control hooks
3. Input sanitization: All API calls are properly sanitized
4. Error boundaries: Errors are contained and don't leak sensitive information
1. Set up the Vortex Next.js SDK backend routes
2. Configure authentication and access control hooks
3. Wrap your app with VortexProvider
4. Use the appropriate hooks in your components
5. Handle errors appropriately for your UX