Add multi-tenant workspaces in an afternoon
Workspaces, membership and roles without designing a tenancy model from scratch or bolting one on later.
In short
useSaaSWorkspaces gives you workspace creation, switching and membership in one hook, with a WorkspaceSwitcher component for the nav. The part worth getting right on day one is that the workspace, not the user, is the unit that owns data, billing and quota.
The tenancy decision is made early, usually implicitly, and it is expensive to revisit. Most products start with "a user has data" and discover eighteen months later that customers wanted "a team has data, and people come and go".
Retrofitting that is a migration across every table you own. If you are starting from a raw Postgres database, or Firestore, rather than a hook, the decision does not go away, it just moves earlier - see Supabase vs BuildBase or Firebase vs BuildBase for what changes when you own the schema yourself.
Before you start
A BuildBase project with the SDK installed and authentication working. This builds directly on whatever auth you already have, since membership is a relationship between a user and a workspace.
Step one: get workspaces and switching from one hook
import { useSaaSWorkspaces, WorkspaceSwitcher } from '@buildbase/sdk/react';
function App() {
const {
workspaces,
currentWorkspace,
createWorkspace,
switchToWorkspace,
addUser,
removeUser,
} = useSaaSWorkspaces();
return (
<nav>
<WorkspaceSwitcher
trigger={(isLoading, ws) => (
<button>{ws?.name ?? 'Select workspace'}</button>
)}
/>
</nav>
);
}What you should see: a switcher in the nav listing every workspace the signed-in
user belongs to, and currentWorkspace changing as they switch. Membership,
invitations and removal are on the same hook rather than a separate system.
Step two: make the workspace the unit that owns things
This is the step that decides whether the afternoon was worth it.
Every row you store should hang off a workspace, not a user. Every quota should
be checked against a workspace. Every subscription should belong to one. The
metering call in
charging per API call takes workspaceId
as its first argument for exactly this reason - the meter and the tenant are the
same concept.
The test: if the person who created the account leaves the company tomorrow, does anything break? If the answer is yes, something is still owned by the user that should be owned by the workspace.
AgentCenter is the one of ours that leans hardest on this. Its whole model is multi-project - agents, runs and permissions all hang off a workspace rather than the person who signed up, and the subscription does too. That was not foresight. It is the shape you get for free when the workspace is the unit from the first commit, and the shape you pay a migration for when it is not.
Step three: roles, before you need them
Roles are easier to add now than after customers have data.
import { WhenPermission, WhenWorkspaceRoles } from '@buildbase/sdk/react';Gate on permission rather than role wherever you can. "Can this person invite someone" survives a reorganisation of your role names; "is this person an admin" does not.
Tip
Decide early whether an invited user without an account gets a pending membership or nothing at all. It sounds like a detail and it is the difference between an invite flow that works and one that quietly drops people.
What people get wrong
One workspace per user, created silently at signup. It looks simpler and it means you never build the switcher. Then a customer asks for a second team and the assumption is baked into every query.
Billing on the user. Covered above and worth repeating, because it is the expensive one.
Roles as strings in your own tables. Once permission checks live in your application code, every new feature needs its own check and they drift.
Install
npm i @buildbase/sdk