Learn the core patterns for building extensions: how to bootstrap your extension, declare UI surfaces, manage cross-surface state, and handle loading and error states gracefully.
## Bootstrap — Entry Point
Set up your extension entry point in `src/index.tsx`. The `createExtension` factory
bootstraps the sandboxed runtime and registers all surfaces with the framework.
```tsx
import { createExtension } from '@stackable-labs/sdk-extension-react'
import { Header } from './surfaces/Header'
import { Content } from './surfaces/Content'
import { Footer } from './surfaces/Footer'
const Extension = () => (
<>
)
// NOTE: extensionId is optional — used when connected to a registered extension
createExtension(() => , { extensionId: 'my-extension' })
```
## Surfaces — Declaring UI Slots
Each surface renders into a specific layout slot in the embedding application.
The `id` prop must match a target declared in your `manifest.json`.
### Header
```tsx
import { Surface, ui } from '@stackable-labs/sdk-extension-react'
export function Header() {
return (
)
}
```
### Content
```tsx
import { Surface, ui } from '@stackable-labs/sdk-extension-react'
export function Content() {
return (
Extension content
)
}
```
### Footer
```tsx
import { Surface, ui } from '@stackable-labs/sdk-extension-react'
export function Footer() {
return (
)
}
```
### Footer Links
```tsx
import { Surface, ui } from '@stackable-labs/sdk-extension-react'
export function FooterLinks() {
return (
)
}
```
## Store — Cross-Surface State & Navigation
Extensions use `createStore` for shared state across surfaces. The store replaces
traditional URL routing — there are no URLs inside the sandbox. Use discriminated
unions for view state to get exhaustive type checking.
```tsx
import { createStore, useStore, Surface, ui } from '@stackable-labs/sdk-extension-react'
// store.ts
type ViewState = { type: 'list' } | { type: 'detail'; id: string }
interface AppState {
viewState: ViewState
}
export const appStore = createStore({
viewState: { type: 'list' },
})
// Content.tsx
export function Content(): React.ReactElement {
const viewState = useStore(appStore, (s) => s.viewState)
const goToDetail = (id: string) => appStore.set({ viewState: { type: 'detail', id } })
const goBack = () => appStore.set({ viewState: { type: 'list' } })
return (
{(viewState.type === 'list') && (
goToDetail('abc123')}>View Detail
)}
{(viewState.type === 'detail') && (
Viewing: {viewState.id}
Back
)}
)
}
```
## Loading States & Guards
Handle loading states and missing context gracefully. Always show a skeleton
while context loads, and guard against missing data before rendering.
```tsx
import { useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
export function Content(): React.ReactElement {
const { loading, customerId } = useContextData()
if (loading) {
return (
)
}
if (!customerId) {
return (
No customer selected
)
}
return (
Customer: {customerId}
)
}
```
## Surface Context
Read host-pushed context for a specific surface using the lower-level
`useSurfaceContext` hook.
```tsx
import { useSurfaceContext, Surface, ui } from '@stackable-labs/sdk-extension-react'
import type { ContextData } from '@stackable-labs/sdk-extension-contracts'
export function Header(): React.ReactElement {
// Lower-level hook — reads host-pushed context for this specific surface
const context = useSurfaceContext() as ContextData
return (
)
}
```