Shell Context
The ShellContext object that provides all platform services to plugins.
Overview#
When a plugin is mounted, it receives a ShellContext object containing all shell services. The Plugin SDK wraps this context in React context providers, making services accessible via hooks.
Accessing the Context#
Via SDK Hooks (Recommended)#
TypeScript
| 1 | import { useShell } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | function MyComponent() { |
| 4 | const shell = useShell(); |
| 5 | // Use shell.auth, shell.eventBus, etc. |
| 6 | } |
Via Mount Function (Advanced)#
TypeScript
| 1 | export function mount(container: HTMLElement, context: ShellContext) { |
| 2 | // Direct access to context |
| 3 | const user = context.auth.getUser(); |
| 4 | const isDark = context.theme.mode === 'dark'; |
| 5 | } |
Service Reference#
auth: IAuthService#
Authentication and authorization.
TypeScript
| 1 | // Check if user is authenticated |
| 2 | context.auth.isAuthenticated(); // boolean |
| 3 | |
| 4 | // Get user info |
| 5 | context.auth.getUser(); // AuthUser | null |
| 6 | |
| 7 | // Get JWT token |
| 8 | await context.auth.getToken(); // string |
| 9 | |
| 10 | // Check roles |
| 11 | context.auth.hasRole('admin'); // boolean |
| 12 | |
| 13 | // Check permissions |
| 14 | context.auth.hasPermission('data', 'write'); // boolean |
navigate: NavigateFunction#
Client-side routing within the shell.
TypeScript
context.navigate('/dashboard');
context.navigate('/plugins/my-plugin/settings');eventBus: IEventBus#
Inter-plugin communication.
TypeScript
| 1 | // Fire-and-forget |
| 2 | context.eventBus.emit('my:event', { data: 'value' }); |
| 3 | |
| 4 | // Listen |
| 5 | const unsub = context.eventBus.on('other:event', (data) => { ... }); |
| 6 | |
| 7 | // Request/Response |
| 8 | const result = await context.eventBus.request('other:query', { q: 'test' }); |
theme: IThemeService#
Theme management.
TypeScript
context.theme.mode; // 'light' | 'dark'
context.theme.toggle(); // Toggle theme
context.theme.setMode('dark');notifications: INotificationService#
User-facing toast notifications.
TypeScript
| 1 | context.notifications.success('Saved!'); |
| 2 | context.notifications.error('Failed'); |
| 3 | context.notifications.warning('Caution'); |
| 4 | context.notifications.info('FYI'); |
integrations: IIntegrationService#
Platform integrations (AI, storage, email).
TypeScript
| 1 | // AI |
| 2 | await context.integrations.ai.complete({ prompt: '...' }); |
| 3 | |
| 4 | // Storage |
| 5 | await context.integrations.storage.upload(file); |
| 6 | |
| 7 | |
| 8 | await context.integrations.email.send({ to, subject, body }); |
logger: ILoggerService#
Structured logging.
TypeScript
context.logger.info('Loaded', { plugin: 'my-plugin' });
context.logger.error('Failed', { error: err.message });permissions: IPermissionService#
Permission checking.
TypeScript
context.permissions.can('resource', 'action'); // boolean
context.permissions.hasRole('admin'); // booleanteam: ITeamContext (Optional)#
Current team context. Available when user is in a team.
TypeScript
| 1 | context.team?.id; // string | null |
| 2 | context.team?.name; // string | null |
| 3 | context.team?.role; // string | null |
| 4 | context.team?.config; // Record<string, unknown> |
version: string#
The shell version string.
TypeScript
context.version; // e.g., '1.0.0'