Admin & Team
Team Management
Admin/team operations UI for deployed apps. Manage memberships, invite existing app users, update roles, remove non-owner members, and bootstrap the first team setup from one internal screen. In Builder preview it stays non-destructive and shows placeholder behavior.
One live admin screen for member listing, invite flow, role changes, owner protection, and setup bootstrap.
Backend remains the source of truth while the UI hides manage actions when currentUserPermissions?.canManageTeam is false.
Uses appId, secureApiCall, team hooks, and backend team endpoints in deployed runtime.
Four things worth knowing
Preview mode stays safe
When isPreview is true the component shows placeholder messaging only. No live mutations run in Builder preview.
Live mode uses backend team APIs
With appId and secureApiCall present, the screen supports full CRUD through /team, /team/users, and /team/init endpoints.
Permission-aware management actions
The UI checks currentUserPermissions?.canManageTeam and hides invite, edit, and remove actions when the current runtime user cannot manage team members.
Cached loading feels faster
useTeamList, useAppUsers, and useTeamInit use per-appId in-memory caching with stale-while-refresh behavior for faster perceived loading.
Find it, drop it, publish
Where to find itAdd it to your admin screen
- Component picker → Admin & Team → Team Management.
- Place it on a protected owner/manager screen.
- Use registry key
team-managementfor builder placement.
Before you publishFour things to check
- Keep navigation admin/team-only even though backend permissions also protect actions.
- Configure header label and theme props in the property editor.
- Ensure runtime passes
appId,secureApiCall, and optionallycurrentUserPermissions. - Publish so deployed runtime can use live team hooks, invite user loading, and bootstrap flow.
What you can configure
| Category | Prop | Type | Default | Description |
|---|---|---|---|---|
| Access | currentUserPermissions | object | injected | Runtime permission object. canManageTeam controls whether invite, edit, and remove actions are shown. |
| Mode | isPreview | boolean | runtime | Preview mode shows non-destructive placeholder UI. Live mode enables backend sync. |
| Data | appId | string | from runtime | App identifier for all team endpoints. |
| Data | secureApiCall | function | injected | Required backend API caller used by useTeamList, useAppUsers, and useTeamInit. |
| Behavior | useBackendData | boolean | true | Hidden editor prop. Team data is expected from backend APIs in deployed runtime. |
| Labels | headerTitle | string | ”Team Management” | Main header title shown at the top of the component. |
| Runtime | customWidth, customHeight | number | injected | Builder/runtime sizing props. Not usually edited manually. |
Feature flags and styling
| Control | Prop | Type | Default | Purpose |
|---|---|---|---|---|
| Theme | backgroundColor | color | #F9FAFB | Overall background color for the screen. |
| Theme | cardBackgroundColor | color | #FFFFFF | Card background color for list rows and surfaces. |
| Theme | primaryColor | color | #3B82F6 | Primary action color for add, confirm, and active controls. |
| Theme | dangerColor | color | #EF4444 | Danger color for destructive actions like member removal. |
| Text | titleColor | color | #1A1A1A | Main title and emphasis text color. |
| Text | subtitleColor | color | #6B7280 | Secondary helper text and metadata color. |
| Borders | borderColor | color | #E5E7EB | Divider and card border color. |
| Layout | borderRadius | number | 12 | Corner radius for cards and modals. |
| Typography | titleFontSize | number | 15 | Font size for member titles and section headings. |
| Typography | subtitleFontSize | number | 13 | Font size for secondary metadata text. |
| Typography | fontFamily | string | Urbanist-SemiBold | Primary font family used across list rows, dialogs, and headers. |
Common mistakes to avoid
Keep team routes protected in navigation
Backend permissions still decide access, but protected owner/manager navigation keeps the runtime experience cleaner and safer.
Use role presets consistently
When changing roles, keep preset permission mappings aligned with app/app/types/team.ts so UI labels and backend expectations stay in sync.
Refresh team state after mutations
After add, update, remove, or init flows, make sure the team hooks refresh cached data so the visible list stays current without stale members.
Sync deployment bundles after source changes
If your deployment flow mirrors source snapshots, run cd app and node collectSourceFiles.js so bundled source files stay up to date.