Structural patterns provide the foundational architecture that every extension uses to bootstrap, render surfaces, manage navigation, and handle loading states. Understanding these patterns ensures your extension integrates smoothly with the host application.
## 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 (
)
}
```