Projects

All Backstage work lives in a project. One page often uses a single project; you can create several with different names.

Creating a project

import {getProject} from '@unseenco/backstage'

const project = getProject('My Project')

getProject is idempotent: the same name returns the same instance.

State

Project state is the JSON snapshot of sheets, objects, keyframes, and overrides. With Studio open, edits are stored in the browser (typically localStorage). For shipping, export state from the outline and load it in code.

Backstage Lite: The same export/import flow works for static-only projects—load { state } in @unseenco/backstage/core-lite and omit Studio from production. See Backstage Lite — Getting started.

import projectState from './state.json'

const project = getProject('My Project', {state: projectState})

Optional project config:

const project = getProject('My Project', {
  state: projectState,
  numberPrecision: 2, // Studio number formatting (default 3)
})

See Prop types — number precision.

Unsaved changes indicator

When in-memory state diverges from the JSON you passed to getProject({ state }), Studio surfaces it in several places:

• Outline toolbar — orange warning badge on the outline toggle; tooltip points to dirty rows.
• Outline rows — objects show a dirty circle (hollow when matching loaded JSON, filled when static overrides or sequence tracks diverge).
• Details Panel — diverged props can be reverted via context menu (Revert to saved value / Revert all to saved value on compounds).

Export again before deploying so production matches what you authored. Details: Studio — saved vs in-memory state.

Assets base URL

If you use image props, configure where exported assets live:

const project = getProject('My Project', {
  state: projectState,
  assets: {baseUrl: '/backstage-assets'},
})

See Assets.

Ready

Studio loads projects asynchronously. Wait before playing:

project.ready.then(() => {
  console.log('Project loaded')
})

Use Project.isReady for a synchronous check.

API

Project API