How to install and build Turbo JS

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

# How to install and build Turbo JS

This guide shows how to get a working `turbo-js` binary. It assumes you have Go 1.26 or later and can use a terminal.

## The short way, from a checkout

```bash
git clone ssh://git@rickub.com/turbo-editors/turbo-js.git
cd turbo-js
make install
```

That builds the editor, puts it where your shell looks for commands, and tells you what it found: the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `typescript-language-server` — the language server — is installed. The build goes to a temporary file first, so a failed build never replaces a working installation.

Then, from any Node.js project:

```bash
turbo-js main.js
```

### Options

```bash
scripts/install.sh --prefix ~/bin     # install somewhere of your choosing
scripts/install.sh --with-server      # install the language server too
scripts/install.sh --uninstall        # remove it again  (make uninstall)
scripts/install.sh --help
```

Without `--prefix`, the editor goes where `go install` would put it: `$GOBIN`, or `$GOPATH/bin` when `GOBIN` is unset — usually `~/go/bin`.

`--with-server` runs `npm install -g typescript-language-server typescript@6`, so it needs `npm` — that is, Node.js; see [How to install Node.js](install-node.md). The `@6` is not optional: TypeScript 7 ships no `tsserver.js`, and a `typescript-language-server` installed beside it fails to start. The installer then checks the server by running `typescript-language-server --version` rather than trusting that the file exists, because a version manager can leave a shim on `PATH` for a Node that has since been removed.

## Just build it, without installing

```bash
make build
./bin/turbo-js main.js
```

`make build` also runs `scripts/check-version.sh` on what it built, so a binary that does not report the version the build meant fails the build rather than shipping.

## From the module proxy, without a checkout

```bash
go install rickub.com/turbo-editors/turbo-js@latest
```

If the command is then "not found", the install directory is not on your `PATH`:

```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```

Turbo JS has not been tagged yet, so until its first release `@latest` names the newest commit and the binary reports `devel` rather than a number; [the version number](../reference/versioning.md) explains why.

## Check it works

```bash
turbo-js -version
turbo-js -list-themes
```

The first names the commit the binary was built from, which is what to quote in a bug report; [the version number](../reference/versioning.md) explains what each form means. The second prints the themes compiled into the binary and tells you where your own would go.

## Variants

- **You only want to run it once**: `go run rickub.com/turbo-editors/turbo-js@latest main.js`
- **You want the binary somewhere specific**: `go build -o /usr/local/bin/turbo-js .`
- **Your terminal has no true colour**: use `turbo-js -theme turbo-classic`, which is built from the sixteen ANSI colours only. `turbo-dark` and `borland-light` use 24-bit colours.

## When something goes wrong

**`the installed binary does not run`.** The installer prints whatever the system said just above that line — read it first, because it names the actual problem.

The installer replaces the binary rather than writing over the one that is there, so a reinstall gives the file a fresh identity. That matters on macOS, which caches a binary's code signature against its inode: writing new bytes into the old inode leaves the cached signature describing something else, and the kernel then refuses to run a binary that built and installed perfectly. If you have an older copy installed by something that used `cp`, removing it first clears any such state:

```bash
scripts/install.sh --uninstall
scripts/install.sh
```

**`Go x.y or later is needed`.** The editor is written in Go, so building it needs a Go toolchain even though it is an editor for JavaScript. The version comes from `go.mod`, so it cannot drift from what the code actually needs.

**`build failed; nothing was installed`.** Your existing installation is untouched — the build goes to a temporary file first. The compiler's own output is printed above the message.

**`the build did not carry its version; nothing was installed`.** The binary built but does not report the version the installer stamped into it — a linker flag naming a symbol that no longer exists, usually. Nothing is installed; the check that failed is described under [the version number](../reference/versioning.md#checked-at-build-time).

**`typescript-language-server is not installed, so there will be no completion`.** Not an error: editing, colouring and themes all work without it. Install the server when you want completion — [How to enable JavaScript completion](enable-completion.md) — or re-run the installer with `--with-server`.

## Terminal requirements

Turbo JS needs a terminal that reports its size and supports mouse reporting — every mainstream one does. It reads `TERM` through tcell; if the display is wrong, check that `TERM` matches your terminal (`xterm-256color` is a safe default).

## See also

- Every flag: [command line reference](../reference/cli.md)
- Getting completion working: [How to enable JavaScript completion](enable-completion.md)
- Node.js itself: [How to install Node.js](install-node.md)
- A guided first session: [Your first JavaScript program in Turbo JS](../tutorials/getting-started.md)