Use the TypeScript workspace builder

@libtmux/workspace 0.1.0-alpha.12 · Source

Apply a workspace to create or reconcile its session, windows, and panes. Start with the complete TypeScript example: it includes imports, project setup, the selected library source, run commands, and private-server cleanup.

Create a session¶

fapplyWorkspace accepts a CServer 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¶

fparseWorkspace from @libtmux/workspace/config validates an object produced by your chosen JSON or YAML parser. fparseWorkspaceYaml uses Bun’s YAML parser. Unknown fields fail validation. With another runtime, parse the document first and pass the resulting object to parseWorkspace.

Review changes and failures¶

fplanWorkspace 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, CWorkspaceApplyError records completed milestones and the failed stage. Its arequiresReplan flag is true; rediscover the current structure before retrying. Completed command effects remain part of the application’s recovery decision.

Topics explains command replay and pruning policies. The configuration parser and builder contracts cover these entry points.