turbo-editors/turbo-js · enable-completion.md

⑂ v1.0.2

enable-completion.md · 127 lines · 8.5 KBmarkdown    Blame HistoryRaw
   1# How to enable JavaScript completion
3This guide shows how to get completion, hovers, go-to-definition, references and error marks working. It assumes Turbo JS is already installed.
5Completion comes from **`typescript-language-server`**, a language server over `tsserver` — the engine behind every editor's JavaScript support — which serves plain JavaScript as well as TypeScript. Turbo JS does not bundle it: editing and colouring work without it, and only completion, the Code menu and the error marks are lost.
7## 1. Install the server, with TypeScript 6
10npm install -g typescript-language-server typescript@6
13Two packages, and the `@6` is not optional. The server is a thin layer over the `typescript` package's `tsserver.js`, and it does not depend on that package, so both have to be installed. **TypeScript 7 — the current major — ships no `tsserver.js`**: it is the native port, with a language server of its own inside its compiler, and `typescript-language-server` installed beside it starts and then refuses with *Could not find a valid TypeScript installation*. TypeScript 6 is the last version that ships the file.
15Turbo JS's own installer will do this for you: `scripts/install.sh --with-server`. [How to install Node.js](install-node.md) covers getting `npm` itself.
17## 2. Make sure Turbo JS can find it
19Turbo JS looks on `PATH` first, then where `npm install -g` writes on a machine that uses a version manager: `$NVM_BIN`, `$NPM_CONFIG_PREFIX/bin` or `~/.npm-global/bin`, `$PNPM_HOME`, `$VOLTA_HOME/bin` or `~/.volta/bin`, then `/usr/local/bin` and `/opt/homebrew/bin`. Check:
22typescript-language-server --version
29If that says "command not found" but Turbo JS still finds it, that is expected and fine: the editor searched the directories above itself.
31## 3. Open a file inside a project
34cd /path/to/your/project
35turbo-js src/index.js
38The server is started in the **project root** — the nearest directory at or above the file you opened that holds a `package.json`. That is where `node_modules/` is and where `import` and `require` resolve from, so it is what decides which modules the server knows. A file with no `package.json` anywhere above it gets the working directory, and the server infers a project from the files it is shown.
40Where you *start* the editor decides where the JavaScript menu's commands run, which is a different matter: start it from the directory holding `package.json` too.
42## 4. Ask for a completion
44Type a name and a dot, or the first letters of a name and **Ctrl-Space**:
46```javascript
47const text = "hello";
51A list drops down under the cursor — `charAt`, `length`, `toUpperCase`, with their signatures. Keep typing to narrow it, **↑ ↓** to walk it, **Enter** or **Tab** to accept, **Escape** to dismiss.
53## What the list holds
55`tsserver` infers types through a language that declares none, so the list is about what your code *is* rather than what it says:
57| Offered | Example |
58| --- | --- |
59| Every name in scope — variables, functions, classes, parameters — including ones typed a second ago and not yet saved | your own `helper` |
60| The members of a value, from its inferred type | `text.` → the String methods; `process.` → `argv`, `env`, `exit` |
61| The exports of a module you imported, and the modules under `node_modules/` when you type a `from "` | `import { readFile } from "node:fs/promises"` |
62| Node's globals and the standard library's | `console`, `Buffer`, `setTimeout`, `structuredClone` |
63| Keywords | `async`, `await`, `class` |
65## Checking what the server is doing
67The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none:
70LSP: no typescript-language-server — npm install -g typescript-language-server typescript@6
73`Run ▸ Language server status` shows the same thing in a box, with the path it found the server at and the directory it started it in.
75## Variants
77**You do not want a language server at all:**
80turbo-js -no-lsp main.js
83**Completion is dead in a window that started without a name.** An Untitled window has no file to announce to the server until it is saved — press **F2** and give it a name ending in `.js`, somewhere under the project. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.
85**The server starts and then dies.** Run it by hand: `echo | typescript-language-server --stdio`. If it prints *Could not find a valid TypeScript installation*, the `typescript` package beside it is version 7 — `npm ls -g typescript` says — and `npm install -g typescript@6` fixes it. A project with its own `typescript` in `node_modules/` is used in preference to the global one, so a project on TypeScript 7 gets the same message: add `typescript@6` to its dev dependencies, or point the server elsewhere.
87**Completion works but nothing is ever underlined.** For a plain `.js` file the server reports **syntax errors** only. Type errors — calling a method that does not exist, passing a string where a number goes — need `// @ts-check` as the first line of the file, or a `jsconfig.json` in the project with `"checkJs": true`. Both are the server's design, not the editor's.
89**The list is empty just after the editor starts.** `tsserver` loads the project after it has said it is ready, and answers an empty list until it has. Ask again a second later.
91**Ctrl-Space does nothing.** tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Use `Run ▸ Completion` instead, or type a `.`.
93**A request takes too long.** Every request gives up after a few seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.
95**You installed the server somewhere unusual.** The editor searches `PATH` and the directories listed above, and nowhere else. Put the directory on `PATH`, or set the variable your version manager defines — `NVM_BIN`, `PNPM_HOME`, `VOLTA_HOME` — in the shell you start the editor from.
97**You would rather use TypeScript 7's own server.** `tsc --lsp --stdio` from the `typescript` package answers every question this editor asks, faster, and publishes **no diagnostics**: it offers them pull-style, which turbo-core does not request, so the gutter would stay blank. That is why it is not the default. [The explanation](../explanation/colouring-and-completion.md) has the measurement.
99## What else the server gives you
101Completion is the loudest thing it does and the least of what it knows. The same connection answers eight more questions, all of them in the **Code** menu and all of them about the symbol under the cursor — no selection needed.
103| Key | What it does | With `typescript-language-server` |
104| --- | --- | --- |
105| **Ctrl-Space** | Completion list | yes |
106| **F1** | Describe the symbol under the cursor | yes — its signature, and the JSDoc comment written just above a declaration of yours |
107| **F12** | Jump to where it is declared | yes, in this file or another |
108| **Shift-F12** | List everywhere it is used | yes — the declaration and every call, as a list to choose from |
109| **Ctrl-T** | Find a symbol by name anywhere in the project | yes |
111And, without a key: *Go to type definition* takes `const shape = new Circle()` to `class Circle`; *Find implementations…* on a class lists its subclasses; *Symbol in file…* lists the file's functions and classes, with each class's methods nested under it; *Problems…* lists every diagnostic.
113All nine questions are answered, and a test in this repository drives each of them against the real server, so this table cannot go stale quietly.
115## The error marks
117Problems the server finds arrive unasked, on open and on every edit. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a `×` in the gutter; and **Code ▸ Problems…** lists all of them.
119For a plain `.js` file they are **syntax errors** — a missing bracket, an unexpected token — reported at the exact column. Type errors need `// @ts-check` or `checkJs`, as above. A program that parses and then fails when run gets no mark: the server never runs anything.
121[How to ask what the code means](ask-about-code.md) walks through the Code menu.
123## See also
125- Why the server is optional, and why it is TypeScript's: [Colouring and completion](../explanation/colouring-and-completion.md)
126- Getting Node and npm: [How to install Node.js](install-node.md)
127- Every key: [keyboard reference](../reference/keyboard.md)

📦 Turbo JS 91999d1 k33g 12h ago	1	# How to enable JavaScript completion
	2
	3	This guide shows how to get completion, hovers, go-to-definition, references and error marks working. It assumes Turbo JS is already installed.
	4
	5	Completion comes from `typescript-language-server`, a language server over `tsserver` — the engine behind every editor's JavaScript support — which serves plain JavaScript as well as TypeScript. Turbo JS does not bundle it: editing and colouring work without it, and only completion, the Code menu and the error marks are lost.
	6
	7	## 1. Install the server, with TypeScript 6
	8
	9	```bash
	10	npm install -g typescript-language-server typescript@6
	11	```
	12
	13	Two packages, and the `@6` is not optional. The server is a thin layer over the `typescript` package's `tsserver.js`, and it does not depend on that package, so both have to be installed. TypeScript 7 — the current major — ships no `tsserver.js`: it is the native port, with a language server of its own inside its compiler, and `typescript-language-server` installed beside it starts and then refuses with Could not find a valid TypeScript installation. TypeScript 6 is the last version that ships the file.
	14
	15	Turbo JS's own installer will do this for you: `scripts/install.sh --with-server`. [How to install Node.js](install-node.md) covers getting `npm` itself.
	16
	17	## 2. Make sure Turbo JS can find it
	18
	19	Turbo JS looks on `PATH` first, then where `npm install -g` writes on a machine that uses a version manager: `$NVM_BIN`, `$NPM_CONFIG_PREFIX/bin` or `~/.npm-global/bin`, `$PNPM_HOME`, `$VOLTA_HOME/bin` or `~/.volta/bin`, then `/usr/local/bin` and `/opt/homebrew/bin`. Check:
	20
	21	```bash
	22	typescript-language-server --version
	23	```
	24
	25	```
	26	6.0.0
	27	```
	28
	29	If that says "command not found" but Turbo JS still finds it, that is expected and fine: the editor searched the directories above itself.
	30
	31	## 3. Open a file inside a project
	32
	33	```bash
	34	cd /path/to/your/project
	35	turbo-js src/index.js
	36	```
	37
	38	The server is started in the project root — the nearest directory at or above the file you opened that holds a `package.json`. That is where `node_modules/` is and where `import` and `require` resolve from, so it is what decides which modules the server knows. A file with no `package.json` anywhere above it gets the working directory, and the server infers a project from the files it is shown.
	39
	40	Where you start the editor decides where the JavaScript menu's commands run, which is a different matter: start it from the directory holding `package.json` too.
	41
	42	## 4. Ask for a completion
	43
	44	Type a name and a dot, or the first letters of a name and Ctrl-Space:
	45
	46	```javascript
	47	const text = "hello";
	48	text.
	49	```
	50
	51	A list drops down under the cursor — `charAt`, `length`, `toUpperCase`, with their signatures. Keep typing to narrow it, ↑ ↓ to walk it, Enter or Tab to accept, Escape to dismiss.
	52
	53	## What the list holds
	54
	55	`tsserver` infers types through a language that declares none, so the list is about what your code is rather than what it says:
	56
	57	\| Offered \| Example \|
	58	\| --- \| --- \|
	59	\| Every name in scope — variables, functions, classes, parameters — including ones typed a second ago and not yet saved \| your own `helper` \|
	60	\| The members of a value, from its inferred type \| `text.` → the String methods; `process.` → `argv`, `env`, `exit` \|
	61	\| The exports of a module you imported, and the modules under `node_modules/` when you type a `from "` \| `import { readFile } from "node:fs/promises"` \|
	62	\| Node's globals and the standard library's \| `console`, `Buffer`, `setTimeout`, `structuredClone` \|
	63	\| Keywords \| `async`, `await`, `class` \|
	64
65	## Checking what the server is doing
66
67	The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none:
68
69	```
70	LSP: no typescript-language-server — npm install -g typescript-language-server typescript@6
71	```
72
73	`Run ▸ Language server status` shows the same thing in a box, with the path it found the server at and the directory it started it in.
74
75	## Variants
76
77	You do not want a language server at all:
78
79	```bash
80	turbo-js -no-lsp main.js
81	```
82
83	Completion is dead in a window that started without a name. An Untitled window has no file to announce to the server until it is saved — press F2 and give it a name ending in `.js`, somewhere under the project. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.
84
85	The server starts and then dies. Run it by hand: `echo \| typescript-language-server --stdio`. If it prints Could not find a valid TypeScript installation, the `typescript` package beside it is version 7 — `npm ls -g typescript` says — and `npm install -g typescript@6` fixes it. A project with its own `typescript` in `node_modules/` is used in preference to the global one, so a project on TypeScript 7 gets the same message: add `typescript@6` to its dev dependencies, or point the server elsewhere.
86
87	Completion works but nothing is ever underlined. For a plain `.js` file the server reports syntax errors only. Type errors — calling a method that does not exist, passing a string where a number goes — need `// @ts-check` as the first line of the file, or a `jsconfig.json` in the project with `"checkJs": true`. Both are the server's design, not the editor's.
88
89	The list is empty just after the editor starts. `tsserver` loads the project after it has said it is ready, and answers an empty list until it has. Ask again a second later.
90
91	Ctrl-Space does nothing. tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Use `Run ▸ Completion` instead, or type a `.`.
92
93	A request takes too long. Every request gives up after a few seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.
94
95	You installed the server somewhere unusual. The editor searches `PATH` and the directories listed above, and nowhere else. Put the directory on `PATH`, or set the variable your version manager defines — `NVM_BIN`, `PNPM_HOME`, `VOLTA_HOME` — in the shell you start the editor from.
96
97	You would rather use TypeScript 7's own server. `tsc --lsp --stdio` from the `typescript` package answers every question this editor asks, faster, and publishes no diagnostics: it offers them pull-style, which turbo-core does not request, so the gutter would stay blank. That is why it is not the default. [The explanation](../explanation/colouring-and-completion.md) has the measurement.
98
99	## What else the server gives you
100
101	Completion is the loudest thing it does and the least of what it knows. The same connection answers eight more questions, all of them in the Code menu and all of them about the symbol under the cursor — no selection needed.
102
103	\| Key \| What it does \| With `typescript-language-server` \|
104	\| --- \| --- \| --- \|
105	\| Ctrl-Space \| Completion list \| yes \|
106	\| F1 \| Describe the symbol under the cursor \| yes — its signature, and the JSDoc comment written just above a declaration of yours \|
107	\| F12 \| Jump to where it is declared \| yes, in this file or another \|
108	\| Shift-F12 \| List everywhere it is used \| yes — the declaration and every call, as a list to choose from \|
109	\| Ctrl-T \| Find a symbol by name anywhere in the project \| yes \|
110
111	And, without a key: Go to type definition takes `const shape = new Circle()` to `class Circle`; Find implementations… on a class lists its subclasses; Symbol in file… lists the file's functions and classes, with each class's methods nested under it; Problems… lists every diagnostic.
112
113	All nine questions are answered, and a test in this repository drives each of them against the real server, so this table cannot go stale quietly.
114
115	## The error marks
116
117	Problems the server finds arrive unasked, on open and on every edit. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a `×` in the gutter; and Code ▸ Problems… lists all of them.
118
119	For a plain `.js` file they are syntax errors — a missing bracket, an unexpected token — reported at the exact column. Type errors need `// @ts-check` or `checkJs`, as above. A program that parses and then fails when run gets no mark: the server never runs anything.
120
121	[How to ask what the code means](ask-about-code.md) walks through the Code menu.
122
123	## See also
124
125	- Why the server is optional, and why it is TypeScript's: [Colouring and completion](../explanation/colouring-and-completion.md)
126	- Getting Node and npm: [How to install Node.js](install-node.md)
127	- Every key: [keyboard reference](../reference/keyboard.md)