README.md

Welcome to your Convex + React (Vite) + Convex Auth app with role-based permissions

This is a Convex project created with npm create convex.

After the initial setup (<2 minutes) you'll have a working full-stack app using:

• Convex as your backend (database, server logic)
• Convex Auth for your authentication implementation
• React as your frontend (web page interactivity)
• Vite for optimized web hosting
• Tailwind and shadcn/ui for building great looking accessible UI fast

Role Based Permissions

This project implements a hierarchical role-based permission system that controls access to different features of the application. The system is built using Convex and consists of three permission levels:

• READ: Basic access level - can view messages
• WRITE: Intermediate access - can view and send messages
• ADMIN: Full access - can view, send, and delete messages

Implementation Details

The permission system is implemented across several files:

1. Schema Definition (schema.ts)

users: defineTable({
  // ... other fields ...
  role: v.optional(
    v.union(v.literal("read"), v.literal("write"), v.literal("admin")),
  ),
});

2. Permission Management (lib/permissions.ts)

The permissions system uses a numeric hierarchy to determine access levels:

const roleHierarchy = {
  read: 0,
  write: 1,
  admin: 2,
};

3. Authentication Integration (auth.ts)

New users are automatically assigned the READ role upon registration:

async afterUserCreatedOrUpdated(ctx, args) {
  if (args.existingUserId) return;
  await ctx.db.patch(args.userId, {
    role: VALID_ROLES.READ,
  });
}

4. Usage Example (messages.ts)

The permission system controls access to different operations:

// Reading messages requires READ access
const hasAccess = await checkPermission(ctx, userId, VALID_ROLES.READ);

// Sending messages requires WRITE access
const hasAccess = await checkPermission(ctx, userId, VALID_ROLES.WRITE);

// Deleting messages requires ADMIN access
const hasAccess = await checkPermission(ctx, userId, VALID_ROLES.ADMIN);

Security Considerations

• Role checks are performed server-side in Convex functions
• Role updates should be restricted to administrators in production
• The permission system is integrated with the authentication system
• Invalid or missing roles default to no access

Get started

If you just cloned this codebase and didn't use npm create convex, run:

npm install
npm run dev

If you're reading this README on GitHub and want to use this template, run:

npm create convex@latest -- -t react-vite-convexauth-shadcn

The app

The app is a basic multi-user chat. Walkthrough of the source code:

• convex/auth.ts configures the available authentication methods
• convex/messages.ts is the chat backend implementation
• src/main.tsx is the frontend entry-point
• src/App.tsx determines which UI to show based on the authentication state
• src/SignInForm.tsx implements the sign-in UI
• src/Chat/Chat.tsx is the chat frontend

Configuring other authentication methods

To configure different authentication methods, see Configuration in the Convex Auth docs.

Learn more

To learn more about developing your project with Convex, check out:

• The Tour of Convex for a thorough introduction to Convex principles.
• The rest of Convex docs to learn about all Convex features.
• Stack for in-depth articles on advanced topics.

Join the community

Join thousands of developers building full-stack apps with Convex:

• Join the Convex Discord community to get help in real-time.
• Follow Convex on GitHub, star and contribute to the open-source implementation of Convex.