@construct-space/sdk

TypeScript SDK for building spaces in the Construct IDE — an AI-powered development environment built with Vue 3 and Tauri.

What is a Space?

Spaces are modular plugins that extend Construct with new capabilities: code editors, design canvases, kanban boards, calendars, terminals, and more. Each space is an independently built IIFE bundle that runs inside the host app.

This SDK provides the full TypeScript API surface — types, store interfaces, composable signatures, and component declarations — so you get autocomplete, type checking, and documentation while building spaces.

Install

npm install @construct-space/sdk
# or
bun add @construct-space/sdk

For shared UI components and UI composables, also install:

npm install @construct-space/ui
# or
bun add @construct-space/ui

How it works

Your space project
  └─ import { useAuthStore } from '@construct/sdk'
       │
       ├─ Dev time → TypeScript types + autocomplete from this package
       └─ Runtime  → Vite externalizes → window.__CONSTRUCT__['@construct/sdk']
                     (Construct host provides actual implementations)

The SDK is a type-and-contract package. It defines what the host exposes, but the host provides the runtime. Your space never bundles this code.

Quick start

Scaffold a new space with the Construct CLI:

construct space scaffold my-space
cd my-space
bun install
construct space dev

Or add the SDK to an existing project:

bun add -d @construct-space/sdk

What's included

Stores (8)

Pinia stores provided by the host app:

import { useAuthStore, useProjectStore, useSettingsStore } from '@construct/sdk'

const auth = useAuthStore()
console.log(auth.currentUser)

| Store | Description | |-------|-------------| | useAuthStore | Authentication state, OAuth login, token management | | useNotificationsStore | Notifications with WebSocket real-time updates | | usePanelsStore | Panel layout management per space | | usePinnedStore | Pinned items (projects, folders, links, tasks) | | usePreferencesStore | User preferences (theme, editor settings, toolbar) | | useProjectStore | Project management, filesystem paths | | useSettingsStore | App-wide settings (company, AI, design, etc.) | | useTranslationsStore | Multi-language translation management |

Composables (~50)

Vue 3 composables for common operations:

import { useApi, useSpaceContext } from '@construct/sdk'

const api = useApi()
const data = await api.get('/items')

Key composables include: useApi, useAuth, useAuthorization, useBilling, useCanvasContext, useChatPanel, useConstructConfig, getConstructRuntime, useCredits, useDateFormat, useDesignActions, useGoogleFonts, useMarkdown, useNotifications, usePanelLayout, usePermissions, useSpaceContext, useStorage, useTelemetry, and many more.

Org-scoped composables

For spaces declaring scope: "org" (or "company") in their manifest — assignee pickers, mentions, team dashboards, permission-aware UI. Each is a focused read slice backed by the shared host org store, so every caller in the session reuses one /org/* round-trip per resource.

import {
  useOrg, useOrgMembers, useOrgTeams, useOrgDepartments, useOrgRoles,
} from '@construct-space/sdk'

const { orgId, orgName, isOrg, isAdmin } = useOrg()
const { members, byUserId }              = useOrgMembers()
const { teams, membersOf }                = useOrgTeams()
const { departments, ofMember }           = useOrgDepartments()
const { can }                             = useOrgRoles()

// Assignee picker
<option v-for="m in members" :key="m.id" :value="m.id">{{ m.name }}</option>

// Permission-gated delete button
<button v-if="can('cards.delete')" @click="deleteCard()">Delete</button>

| Composable | Returns | Use case | |---|---|---| | useOrg | orgId, orgName, currentOrg, isOrg, roles, isAdmin, refresh() | Basic context; replaces reach-ins to useAuthStore + useOrgStore | | useOrgMembers | members, byId, byUserId, memberCount, refresh() | Assignee picker, mentions, resolving assignee_user_id to a name | | useOrgTeams | teams, membersOf(teamId), teamsOf(memberId), refresh() | Team filters, "assign to team", per-team dashboards | | useOrgDepartments | departments, ofMember(memberId), membersOf(deptId), refresh() | Group headers, dept filters | | useOrgRoles | roles, byName, ofMember(memberId), can(perm), refresh() | Role-aware UI; .can(perm) gates off the active user's roles |

All return reactive ComputedRefs and auto-fire fetchAll on first use — no need to kick off loading from onMounted.

Shared UI

Shared UI components now live in @construct-space/ui:

import { Button, Modal, Notification, useNotification } from '@construct-space/ui'

The SDK remains the contract for host APIs, stores, runtime config, and shared types.

Context Bus

Cross-space communication via pub/sub:

import { publishSpaceContext, subscribeSpaceContext } from '@construct/sdk'

// Publish state from your space
publishSpaceContext({
  spaceId: 'my-space',
  type: 'tasks',
  summary: { total: 42, completed: 30 },
  timestamp: Date.now(),
})

// Subscribe to updates from other spaces
const unsub = subscribeSpaceContext('tasks', (payload) => {
  console.log(payload.summary)
})

Types

All TypeScript interfaces are available for direct import:

import type {
  AuthUser,
  LocalProject,
  DesignNode,
  PanelLayout,
  SpaceType,
  ApiResponse,
} from '@construct/sdk'

TypeScript setup

In your space's tsconfig.json, map the import alias:

{
  "compilerOptions": {
    "paths": {
      "@construct/sdk": ["./node_modules/@construct-space/sdk/dist/index.d.ts"]
    }
  }
}

For local development (monorepo), point to the source:

{
  "compilerOptions": {
    "paths": {
      "@construct/sdk": ["../construct-sdk/src/index.ts"]
    }
  }
}

Vite configuration

Spaces use the Construct CLI's Vite preset which automatically externalizes @construct/sdk:

// vite.config.ts
import { createSpaceBuildConfig } from 'construct/vite'

export default createSpaceBuildConfig('my-space')

API reference

Full type definitions are included in the package. Use your editor's "Go to Definition" to explore the complete API.

License

MIT