github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-23 23:52:05 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[PR #4348] [CLOSED] feat(workspaces): organization workspaces plugin support #5323

New Issue
Closed
opened 2026-03-13 12:18:44 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-03-13 12:18:44 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/better-auth/better-auth/pull/4348
Author: @XavierGeerinck
Created: 9/1/2025
Status: ❌ Closed

Base: main ← Head: feat-plugin-workspace

📝 Commits (10+)

  • 4f0697f feat(workspaces): organization workspaces plugin
  • c04a97b docs(workspace): add docs
  • 0cb047b docs(workspace): cleanup some unused docs as they were moved to the main plugin docs mdx
  • d454701 chore: linting fixes
  • e2d0685 test: increase test timeout as it's a big E2E test
  • 8c057d0 fix(workspaces): fix session handling issue
  • 5bfb3de fix: typecheck issues
  • eae126b linting issues
  • 8554b18 fix: address PR reviewer issues
  • e51af2c fix: linting issues

📊 Changes

57 files changed (+7736 additions, -283 deletions)

View changed files

📝 demo/nextjs/app/globals.css (+91 -51)
📝 docs/app/docs/[[...slug]]/page.tsx (+2 -0)
📝 docs/components/icons.tsx (+23 -0)
➕ docs/components/mdx/add-to-cursor.tsx (+41 -0)
📝 docs/components/sidebar-content.tsx (+5 -0)
📝 docs/content/docs/authentication/discord.mdx (+42 -16)
📝 docs/content/docs/concepts/oauth.mdx (+201 -30)
➕ docs/content/docs/integrations/convex.mdx (+347 -0)
📝 docs/content/docs/introduction.mdx (+48 -7)
📝 docs/content/docs/plugins/device-authorization.mdx (+6 -6)
➕ docs/content/docs/plugins/organization-workspace.mdx (+855 -0)
📝 packages/better-auth/build.config.ts (+1 -0)
📝 packages/better-auth/package.json (+14 -1)
📝 packages/better-auth/src/__snapshots__/init.test.ts.snap (+2 -1)
📝 packages/better-auth/src/adapters/adapter-factory/index.ts (+5 -2)
📝 packages/better-auth/src/adapters/adapter-factory/test/adapter-factory.test.ts (+47 -0)
📝 packages/better-auth/src/adapters/adapter-factory/types.ts (+1 -0)
📝 packages/better-auth/src/adapters/drizzle-adapter/drizzle-adapter.ts (+1 -1)
📝 packages/better-auth/src/adapters/kysely-adapter/dialect.ts (+4 -0)
📝 packages/better-auth/src/adapters/kysely-adapter/kysely-adapter.ts (+1 -1)

...and 37 more files

📄 Description

Introducing a comprehensive workspace management solution that adds project-level organization within Better Auth organizations, featuring granular permissions and team integration.

✨ Features

  • Workspace Management - Full CRUD operations with metadata support
  • Member Management - Add/remove users and teams with role-based access
  • Hierarchical Permissions - Organization → Workspace → Member access control
  • Team Integration - Seamless integration with organization teams
  • Auto Creation - Default workspace creation for new organizations
  • Type Safety - Complete TypeScript support with proper inference

🏗️ Architecture

Organizations
├─ Members (owner, admin, member)
├─ Teams  
└─ Workspaces
   ├─ Individual Members (owner, admin, member)
   └─ Team Members

🚀 Quick Start

Installation

// Server
import { betterAuth } from "better-auth"
import { organization, workspace } from "better-auth/plugins"

export const auth = betterAuth({
  plugins: [
    organization(),
    workspace()
  ]
})

// Client  
import { createAuthClient } from "better-auth/client"
import { organizationClient, workspaceClient } from "better-auth/client/plugins"

export const client = createAuthClient({
  plugins: [organizationClient(), workspaceClient()]
})

Usage

// Create workspace
const workspace = await client.workspace.create({
  name: "Development Team",
  metadata: { project: "alpha", priority: "high" }
})

// Add member
await client.workspace.addMember({
  workspaceId: workspace.id,
  userId: "user-123", 
  role: "admin"
})

// Add team
await client.workspace.addTeamMember({
  workspaceId: workspace.id,
  teamId: "team-456",
  role: "member"
})

📊 API Overview

Workspace Operations

  • workspace.create() - Create new workspace
  • workspace.list() - List user's workspaces
  • workspace.update() - Update workspace details
  • workspace.delete() - Remove workspace
  • workspace.setActive() - Set active workspace

Member Management

  • workspace.addMember() - Add individual member
  • workspace.removeMember() - Remove member
  • workspace.updateMemberRole() - Change member role
  • workspace.listMembers() - List all members

Team Integration

  • workspace.addTeamMember() - Add team to workspace
  • workspace.removeTeamMember() - Remove team
  • workspace.updateTeamMemberRole() - Update team role
  • workspace.listTeamMembers() - List workspace teams

🔐 Permissions

Role Create Manage Members Update Delete
Org Owner ✅ ✅ ✅ ✅
Org Admin ✅ ✅ ✅ ✅
Workspace Owner N/A ✅ ✅ ✅
Workspace Admin N/A ✅ ✅ ❌
Member ❌ ❌ ❌ ❌

⚙️ Configuration

workspace({
  createDefaultWorkspace: true,
  defaultWorkspaceName: "General",
  schema: {
    workspace: {
      additionalFields: {
        priority: { type: "string" },
        archived: { type: "boolean" }
      }
    }
  },
  workspaceHooks: {
    beforeCreateWorkspace: async ({ workspace, user }) => {
      // Custom logic
    },
    afterCreateWorkspace: async ({ workspace, user }) => {
      // Post-creation setup  
    }
  }
})

📋 Database Schema

New Tables:

  • workspace - Core workspace entity
  • workspaceMember - Individual member assignments
  • workspaceTeamMember - Team assignments

Session Extension:

  • activeWorkspaceId - Track user's current workspace

🧪 Testing

All tests pass, ran through:

pnpm test src/plugins/organization-workspace/workspace.test.ts
image

It is expected to receive errors on ID creation as manual ID creation is not allowed in the memory adapter, thus it gets ignored. This is as intended

💼 Sponsorship

This feature was developed and contributed by Scrydon as part of our commitment to open-source software and the Better Auth ecosystem.

Summary by cubic

Adds a Workspace plugin that lets organizations create project-level workspaces with role-based access and team support. Includes full CRUD, member/team management, active workspace state, docs, and tests.

  • New Features

    • Workspace CRUD with metadata and optional slug; optional default workspace on org creation.
    • Member and team management with roles; permission checks and error codes.
    • Active workspace stored in session; middleware for workspace routes.
    • Server and client plugins with typed endpoints (/workspace/*).
    • Docs and README added; build and exports wired.

  • Migration

    • Update to better-auth >= 1.3.8-beta.1.
    • Register the workspace plugin after the organization plugin on server and client.
    • Run DB migrations to add workspace, workspaceMember, and workspaceTeamMember tables (plus active workspace session field if used).

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/better-auth/better-auth/pull/4348 **Author:** [@XavierGeerinck](https://github.com/XavierGeerinck) **Created:** 9/1/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat-plugin-workspace` --- ### 📝 Commits (10+) - [`4f0697f`](https://github.com/better-auth/better-auth/commit/4f0697f345fe417084621d647e639e4e677e6af9) feat(workspaces): organization workspaces plugin - [`c04a97b`](https://github.com/better-auth/better-auth/commit/c04a97b8a6c761c43e25fcb777bd0ea24b52e477) docs(workspace): add docs - [`0cb047b`](https://github.com/better-auth/better-auth/commit/0cb047b4a214103041b16d81eabf6def7db3cd9e) docs(workspace): cleanup some unused docs as they were moved to the main plugin docs mdx - [`d454701`](https://github.com/better-auth/better-auth/commit/d454701531270fea1641ebb24626d148a6cd552e) chore: linting fixes - [`e2d0685`](https://github.com/better-auth/better-auth/commit/e2d0685ff7cf494ec00b83ec162d5b527d03ae5d) test: increase test timeout as it's a big E2E test - [`8c057d0`](https://github.com/better-auth/better-auth/commit/8c057d0162e66661e8a2e1b74890b057eaf50eba) fix(workspaces): fix session handling issue - [`5bfb3de`](https://github.com/better-auth/better-auth/commit/5bfb3de1805f0b6993c74c7a13a452b770d4c480) fix: typecheck issues - [`eae126b`](https://github.com/better-auth/better-auth/commit/eae126b66ebb897fa94ada4bdff12504aa077111) linting issues - [`8554b18`](https://github.com/better-auth/better-auth/commit/8554b18b47fec5a9df06173e62ccea3338a7d535) fix: address PR reviewer issues - [`e51af2c`](https://github.com/better-auth/better-auth/commit/e51af2cb2026386a670bc741aac475ac7c1516c4) fix: linting issues ### 📊 Changes **57 files changed** (+7736 additions, -283 deletions) <details> <summary>View changed files</summary> 📝 `demo/nextjs/app/globals.css` (+91 -51) 📝 `docs/app/docs/[[...slug]]/page.tsx` (+2 -0) 📝 `docs/components/icons.tsx` (+23 -0) ➕ `docs/components/mdx/add-to-cursor.tsx` (+41 -0) 📝 `docs/components/sidebar-content.tsx` (+5 -0) 📝 `docs/content/docs/authentication/discord.mdx` (+42 -16) 📝 `docs/content/docs/concepts/oauth.mdx` (+201 -30) ➕ `docs/content/docs/integrations/convex.mdx` (+347 -0) 📝 `docs/content/docs/introduction.mdx` (+48 -7) 📝 `docs/content/docs/plugins/device-authorization.mdx` (+6 -6) ➕ `docs/content/docs/plugins/organization-workspace.mdx` (+855 -0) 📝 `packages/better-auth/build.config.ts` (+1 -0) 📝 `packages/better-auth/package.json` (+14 -1) 📝 `packages/better-auth/src/__snapshots__/init.test.ts.snap` (+2 -1) 📝 `packages/better-auth/src/adapters/adapter-factory/index.ts` (+5 -2) 📝 `packages/better-auth/src/adapters/adapter-factory/test/adapter-factory.test.ts` (+47 -0) 📝 `packages/better-auth/src/adapters/adapter-factory/types.ts` (+1 -0) 📝 `packages/better-auth/src/adapters/drizzle-adapter/drizzle-adapter.ts` (+1 -1) 📝 `packages/better-auth/src/adapters/kysely-adapter/dialect.ts` (+4 -0) 📝 `packages/better-auth/src/adapters/kysely-adapter/kysely-adapter.ts` (+1 -1) _...and 37 more files_ </details> ### 📄 Description Introducing a comprehensive workspace management solution that adds project-level organization within Better Auth organizations, featuring granular permissions and team integration. ## ✨ Features - **Workspace Management** - Full CRUD operations with metadata support - **Member Management** - Add/remove users and teams with role-based access - **Hierarchical Permissions** - Organization → Workspace → Member access control - **Team Integration** - Seamless integration with organization teams - **Auto Creation** - Default workspace creation for new organizations - **Type Safety** - Complete TypeScript support with proper inference ## 🏗️ Architecture ``` Organizations ├─ Members (owner, admin, member) ├─ Teams └─ Workspaces ├─ Individual Members (owner, admin, member) └─ Team Members ``` ## 🚀 Quick Start ### Installation ```typescript // Server import { betterAuth } from "better-auth" import { organization, workspace } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ organization(), workspace() ] }) // Client import { createAuthClient } from "better-auth/client" import { organizationClient, workspaceClient } from "better-auth/client/plugins" export const client = createAuthClient({ plugins: [organizationClient(), workspaceClient()] }) ``` ### Usage ```typescript // Create workspace const workspace = await client.workspace.create({ name: "Development Team", metadata: { project: "alpha", priority: "high" } }) // Add member await client.workspace.addMember({ workspaceId: workspace.id, userId: "user-123", role: "admin" }) // Add team await client.workspace.addTeamMember({ workspaceId: workspace.id, teamId: "team-456", role: "member" }) ``` ## 📊 API Overview ### Workspace Operations - `workspace.create()` - Create new workspace - `workspace.list()` - List user's workspaces - `workspace.update()` - Update workspace details - `workspace.delete()` - Remove workspace - `workspace.setActive()` - Set active workspace ### Member Management - `workspace.addMember()` - Add individual member - `workspace.removeMember()` - Remove member - `workspace.updateMemberRole()` - Change member role - `workspace.listMembers()` - List all members ### Team Integration - `workspace.addTeamMember()` - Add team to workspace - `workspace.removeTeamMember()` - Remove team - `workspace.updateTeamMemberRole()` - Update team role - `workspace.listTeamMembers()` - List workspace teams ## 🔐 Permissions | Role | Create | Manage Members | Update | Delete | |------|--------|---------------|--------|--------| | **Org Owner** | ✅ | ✅ | ✅ | ✅ | | **Org Admin** | ✅ | ✅ | ✅ | ✅ | | **Workspace Owner** | N/A | ✅ | ✅ | ✅ | | **Workspace Admin** | N/A | ✅ | ✅ | ❌ | | **Member** | ❌ | ❌ | ❌ | ❌ | ## ⚙️ Configuration ```typescript workspace({ createDefaultWorkspace: true, defaultWorkspaceName: "General", schema: { workspace: { additionalFields: { priority: { type: "string" }, archived: { type: "boolean" } } } }, workspaceHooks: { beforeCreateWorkspace: async ({ workspace, user }) => { // Custom logic }, afterCreateWorkspace: async ({ workspace, user }) => { // Post-creation setup } } }) ``` ## 📋 Database Schema **New Tables:** - `workspace` - Core workspace entity - `workspaceMember` - Individual member assignments - `workspaceTeamMember` - Team assignments **Session Extension:** - `activeWorkspaceId` - Track user's current workspace ## 🧪 Testing All tests pass, ran through: ```bash pnpm test src/plugins/organization-workspace/workspace.test.ts ``` <img width="772" height="472" alt="image" src="https://github.com/user-attachments/assets/ba2cc3c1-4d3c-4f19-8749-43d9093c38bb" /> It is expected to receive errors on ID creation as manual ID creation is not allowed in the memory adapter, thus it gets ignored. This is as intended ## 💼 Sponsorship This feature was developed and contributed by **Scrydon** as part of our commitment to open-source software and the Better Auth ecosystem. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Adds a Workspace plugin that lets organizations create project-level workspaces with role-based access and team support. Includes full CRUD, member/team management, active workspace state, docs, and tests. - **New Features** - Workspace CRUD with metadata and optional slug; optional default workspace on org creation. - Member and team management with roles; permission checks and error codes. - Active workspace stored in session; middleware for workspace routes. - Server and client plugins with typed endpoints (/workspace/*). - Docs and README added; build and exports wired. - **Migration** - Update to better-auth >= 1.3.8-beta.1. - Register the workspace plugin after the organization plugin on server and client. - Run DB migrations to add workspace, workspaceMember, and workspaceTeamMember tables (plus active workspace session field if used). <!-- End of auto-generated description by cubic. --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-03-13 12:18:44 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#5323
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?