# Use the TypeScript workspace builder

Source: https://libtmux.org/en/ts/latest/workspace/internals/guides/

> Apply a workspace, review planned changes, and handle partial failures.

**Workspace Manager concept example** A working example of the core library. It can change without notice.

Apply a workspace to create or reconcile its session, windows, and panes. Start
with the [complete TypeScript example](https://libtmux.org/en/ts/latest/workspace/internals/examples/): it includes imports,
project setup, the selected library source, run commands, and private-server
cleanup.

## Create a session

[`applyWorkspace`](<https://libtmux.org/en/ts/latest/workspace/reference/builder-applyworkspace/>) accepts a [`Server`](<https://libtmux.org/en/ts/latest/reference/server-server/>) and workspace configuration. Await it to
receive the resulting session. Pane commands can still be running when it
returns.

The complete example uses a private socket and registers cleanup before
applying the workspace. A failed apply can leave a session or some of its
windows in place. For a workspace you want to keep, choose the intended server
explicitly and retain the returned session.

## Read configuration

[`parseWorkspace`](<https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspace/>) from `@libtmux/workspace/config` validates an object produced
by your chosen JSON or YAML parser. [`parseWorkspaceYaml`](<https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspaceyaml/>) uses Bun's YAML parser.
Unknown fields fail validation. With another runtime, parse the document first
and pass the resulting object to [`parseWorkspace`](<https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspace/>).

## Review changes and failures

[`planWorkspace`](<https://libtmux.org/en/ts/latest/workspace/reference/builder-planworkspace/>) reads the server and reports planned structural creation,
removal, retention, and window renames. Options, layouts, focus, and command
effects are outside that plan. Review removals and retained entries, then apply
promptly. Replan after an outside change.

When an apply fails after mutation may have started, [`WorkspaceApplyError`](<https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplyerror/>)
records completed milestones and the failed stage. Its [`requiresReplan`](<https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplyerror-requiresreplan/>) flag
is true; rediscover the current structure before retrying. Completed command
effects remain part of the application's recovery decision.

[Topics](https://libtmux.org/en/ts/latest/workspace/internals/topics/) explains command replay and pruning policies. The
[configuration parser](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/workspace/src/config.ts)
and [builder contracts](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/workspace/src/builder.ts)
cover these entry points.