Workspaces, members and invites
64 files3 packages1 dependency
This pack adds workspaces to your app, so your users can work together with their team in shared spaces.
- Workspaces with members and roles, powered by the Permissions package.
- A personal workspace for every new user, created at signup.
- Users can belong to as many workspaces as they need.
- Every route and query scoped to the current workspace.
- Email invites. New users accept them by signing up, and existing users by signing in.
- Member management. Owners can change roles and remove members, and any member can leave.
- Workspace settings, where owners can rename the workspace.
Depends on Auth
This pack builds on the Auth pack's User model, login, signup and email setup, so apply the Auth pack first.
Apply the workspaces pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=workspaces --agent=claude
$ npx @adonisplus/flow apply --pack=workspaces --agent=codex
$ npx @adonisplus/flow apply --pack=workspaces --agent=cursor
$ npx @adonisplus/flow apply --pack=workspaces --agent=opencode
After applying, Flow will make the following changes to your app.
- Find the page users land on after login, and make it open the workspace they used last.
- Add a page layout with a header and a layout for the settings pages, if your app doesn't have them yet.
- Install the packages the pack needs.
- Add the workspace tables, models and roles, and the authorization checks that decide who can do what.
- Add the workspace, members and invite pages, plus the invite email.
- Create a personal workspace at signup, and let users accept an invite when they sign up or log in.
- Restyle the new pages to match your app's design.
- Run the tests, walk through each flow in the browser, and show you the result.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have. This is the shape of an apply onto the Vue starter kit with the auth pack in place.
Foundation
app.vueinertia/layouts/app.vueRenders the workspace switcher in the header.editedsettings.vueinertia/layouts/settings.vueAdds the workspace section to the settings sidebar.edited
Permissions
permissions.tsstart/permissions.tsDefines the workspace, member and invite permissions.createdpermissions.tstypes/permissions.tsThe type of a permission key.createdworkspace-context.md.flow/custom/docs/workspace-context.mdTells your coding agent what the workspace middleware loads.created
Migrations
xxxx_create_workspaces_table.tsdatabase/migrations/xxxx_create_workspaces_table.tsCreates theworkspacestable.createdxxxx_create_memberships_table.tsdatabase/migrations/xxxx_create_memberships_table.tsCreates themembershipstable.createdxxxx_create_roles_table.tsdatabase/migrations/xxxx_create_roles_table.tsCreates therolestable.createdxxxx_create_membership_roles_table.tsdatabase/migrations/xxxx_create_membership_roles_table.tsCreates themembership_rolestable.createdxxxx_create_invitations_table.tsdatabase/migrations/xxxx_create_invitations_table.tsCreates theinvitationstable.createdschema_rules.tsdatabase/schema_rules.tsTypes a role's permissions as a list of keys.edited
Models & seeder
workspace.tsapp/models/workspace.tsAdds invites, and makes sure every workspace keeps an owner.createdmembership.tsapp/models/membership.tsA user in a workspace, with their roles.createdrole.tsapp/models/role.tsA role with its permissions.createduser.tsapp/models/user.tsAdds the memberships and the workspace queries.editedrole_seeder.tsdatabase/seeders/role_seeder.tsCreates the owner and member roles.createdsession_keys.tsapp/values/session_keys.tsThe session key that stores the user's last opened workspace.created
Transformers
workspace_transformer.tsapp/transformers/workspace_transformer.tsSerializes a workspace.createdmember_transformer.tsapp/transformers/member_transformer.tsSerializes a member, with the actions the signed-in user can take on them.createdinvitation_transformer.tsapp/transformers/invitation_transformer.tsSerializes a pending invite.createdrole_transformer.tsapp/transformers/role_transformer.tsSerializes a role.created
Policy & validators
member_policy.tsapp/policies/member_policy.tsDecides who can change a membership, remove a member or leave.createdworkspace.tsapp/validators/workspace.tsValidates the create and rename forms.createdmember.tsapp/validators/member.tsValidates a role change.createduser.tsapp/validators/user.tsAdds the invite field to login and signup, and the invite validator.editedinvitation_roles_missing_exception.tsapp/exceptions/invitation_roles_missing_exception.tsRaised when an invite names a role that no longer exists.created
Middleware
workspace_middleware.tsapp/middleware/workspace_middleware.tsLoads the workspace and the signed-in user's membership.createdinitialize_bouncer_middleware.tsapp/middleware/initialize_bouncer_middleware.tsChecks permissions against the user's membership.createdauthorize_middleware.tsapp/middleware/authorize_middleware.tsRejects a request when the user lacks the route's permission.createdinertia_middleware.tsapp/middleware/inertia_middleware.tsShares the current workspace and the list of workspaces.editedinertia.tsconfig/inertia.tsEncrypts the browser history.edited
Controllers
landing_workspace_controller.tsapp/controllers/landing_workspace_controller.tsOpens the user's last opened workspace.createdworkspaces_controller.tsapp/controllers/workspaces_controller.tsLists, creates, shows and renames workspaces.createdmembers_controller.tsapp/controllers/members_controller.tsLists members, changes their role and removes them.createdmembership_controller.tsapp/controllers/membership_controller.tsLets the signed-in user leave the workspace.createdinvitations_controller.tsapp/controllers/invitations_controller.tsSends, resends and revokes invites.createdinvites_controller.tsapp/controllers/invites_controller.tsShows an invite and accepts it.createdsession_controller.tsapp/controllers/session_controller.tsReturns to the invite after login.editednew_account_controller.tsapp/controllers/new_account_controller.tsCreates the personal workspace, and skips verification for an invited email.edited
Mailer & email template
invitation_provision.tsapp/mails/invitation_provision.tsThe invite email.createdinvitation.edgeresources/views/emails/invitation.edgeThe body of the invite email.created
Routes
routes.tsstart/routes.tsAdds the workspace, member and invite routes.edited
Screens
workspace_switcher.vueinertia/components/workspace_switcher.vueSwitches workspaces and creates a new one.createdconfirm_dialog.vueinertia/components/confirm_dialog.vueConfirms removing a member and leaving a workspace.createdshow.vueinertia/pages/workspaces/show.vueThe home page of a workspace.createdcreate.vueinertia/pages/workspaces/create.vueCreates a workspace, with up to eight invites.creatededit.vueinertia/pages/workspaces/edit.vueRenames the workspace.createdindex.vueinertia/pages/members/index.vueLists members and pending invites, with the invite form.createdshow.vueinertia/pages/invites/show.vueShows an invite with its join, sign-in and signup actions.createdlogin.vueinertia/pages/auth/login.vueKeeps the invite through login.editedsignup.vueinertia/pages/auth/signup.vueKeeps the invite through signup, and shows the invited email.edited
Tests
bootstrap.tstests/bootstrap.tsSeeds the roles before the tests.editeduser_factory.tsdatabase/factories/user_factory.tsGives each user a personal workspace.editedworkspaces.tstests/helpers/workspaces.tsHelpers to add members and invites.createdlogin.spec.tstests/browser/auth/login.spec.tsLogin lands the user in a workspace.editedsignup.spec.tstests/browser/auth/signup.spec.tsSignup creates a personal workspace.editedemail_verification.spec.tstests/browser/auth/email_verification.spec.tsEmail verification lands the user in a workspace.editedcreate.spec.tstests/browser/workspaces/create.spec.tsCreating a workspace, with and without invites.createdgeneral.spec.tstests/browser/workspaces/general.spec.tsRenaming a workspace.createdmembers.spec.tstests/browser/workspaces/members.spec.tsChanging roles, removing members and leaving.createdinvitations.spec.tstests/browser/workspaces/invitations.spec.tsSending, resending and revoking invites.createdaccept.spec.tstests/browser/workspaces/accept.spec.tsAccepting an invite, and links that have stopped working.createdaccess.spec.tstests/browser/workspaces/access.spec.tsNon-members, and members without the required permission.createdswitcher.spec.tstests/browser/workspaces/switcher.spec.tsSwitching workspaces.created
Configuration
Section titled "Configuration"The withInvitations() mixin on the Workspace model stores the invites. Every option is optional.
expiresInstring | number7 days.tablestringinvitations.withInvitations<{ roleIds: number[] }>({ expiresIn: '3 days' })Owner and member roles
Section titled "Owner and member roles"The pack ships with two roles, owner and member. Owners can rename the workspace, manage members and send invites. Members can use the workspace and leave it. You can add as many roles and permissions as your app needs.
To add a permission, define it in start/permissions.ts and check it in your code with Bouncer. See Bouncer integration.
export const permissions = definePermissions({
workspace: {
update: 'Rename the workspace',
delete: 'Delete the workspace',
},
})To add a role or change a role's permissions, edit the role seeder and run it again. The role select on the members page lists every role in the table. See Managing roles and Defining permissions.
await Role.updateOrCreateMany('name', [
{ name: 'owner', permissions: [, /* ... */ 'workspace.delete'] },
{ name: 'member', permissions: [] },
{ name: 'billing', permissions: ['invitation.view'] },
])Every user gets a personal workspace
Section titled "Every user gets a personal workspace"Signup creates a workspace named after the user's first name, or after their email if they didn't give a name. A user who leaves their last workspace gets a new personal one.
Only members can open a workspace
Section titled "Only members can open a workspace"Workspace pages live under /w/<slug>. Anyone who isn't a member of the workspace gets a 404. The slug is generated from the name when the workspace is created, and renaming the workspace doesn't change it, so existing links keep working.
Login opens the last used workspace
Section titled "Login opens the last used workspace"After login, users land in the workspace they opened last. If there isn't one, they land in the first workspace they joined.
A workspace always keeps an owner
Section titled "A workspace always keeps an owner"The last owner can't leave the workspace or lose the owner role. If two owners try to leave at the same moment, only one of them succeeds.
Members can't change their own role
Section titled "Members can't change their own role"A member's own row has no role select and no remove button. To leave a workspace, they use the Leave button.
Invite links only work for the invited email
Section titled "Invite links only work for the invited email"If someone signs in with a different email, they're told the invite isn't valid. Resending an invite creates a new link and invalidates the old one. If the invite went out less than a minute ago, resending it doesn't send another email. Revoking an invite also invalidates its link.
Invited users skip email verification
Section titled "Invited users skip email verification"Opening the invite link already proves the user owns the email address, so signing up through it doesn't send a verification email.
Logout clears the browser history
Section titled "Logout clears the browser history"Every page after login shows workspace data, so the app encrypts the browser history for those pages and clears it on logout. After logout, the back button can't bring those pages back.
Added in Flow 1.1.0.