Run the workshop in the project that owns your OpenTUI components. The public website and hosted Docs are separate from this local development process.

1. Prerequisites

Use Bun, not Node.js, to run Textbook. Your project should use @opentui/core for its terminal components. When contributing to Textbook itself, use the repository's Devenv environment for its toolchain.

bun --version

2. Installation

Add textbook-sh to your project dependencies. The npm name textbook is an unrelated package:

bun add -d textbook-sh

Installing adds the textbook and tb executables to your project, so bunx textbook … resolves to your local install. Without a local install, run it by package name with bunx textbook-sh ….

3. Add a story

Create a file such as src/button.stories.ts using the Writing Stories guide. Textbook discovers *.stories.ts files under the current directory by default. Installing Textbook does not add the repository's example catalog to your project.

4. Start your local Canvas

bunx textbook-sh web --open
# Or select the directory containing your stories:
bunx textbook-sh web --cwd src --port 8008 --open

The command prints the local URL, normally http://localhost:8008/. Keep the process running. Select a story in the sidebar, then click the terminal to interact with it. A link to localhost means the reader's machine, not a hosted demo.

5. Read Docs online or locally

Continue reading hosted Docs, or start a separate local Docs process:

bunx textbook-sh docs --open

Local Docs default to port 8001. They do not start a terminal renderer. For project-specific documentation, run Docs and Canvas with the same working directory and story discovery options:

# Terminal 1: run your components
bunx textbook-sh web --cwd src --open
# Terminal 2: browse their local documentation
bunx textbook-sh docs --cwd src --open

On loopback addresses, local Docs adds a Project Stories section with documented props and links to the matching local Canvas story. Repository example guides only get a Canvas link when that example is loaded in the Docs registry. Canvas still needs to be running with the same story files; a link does not start it. Hosted Docs show the guide without these project controls.

The landing website is deployed separately and has no CLI command.

Terminal TUI and command help

You can also run Textbook directly inside your current terminal session:

bunx textbook-sh
bunx textbook-sh --help
bunx textbook-sh --man

For repository contributors, devenv tasks run textbook:landing, textbook:docs, and textbook:canvas start the three development surfaces on ports 8000, 8001, and 8008 respectively. These tasks belong to the Textbook repository, not projects that merely install the package.

Introduction