How to insert snippets from a menu

 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

# How to insert snippets from a menu

This guide shows how to set up reusable pieces of text and put them into a file at the cursor. It assumes Turbo JS is already installed.

## Get a starter file

Start the editor **from the project's own directory**, then choose **Snippets ▸ Create snippets file** (`Alt-N`, then `C`).

That writes `.turbo-js/snippets.toml`, filled in with a handful of JavaScript constructs, one for `package.json` and a couple of general ones, and opens it — coloured, because Turbo JS colours TOML:

```toml
[[snippet]]
name = "for of"
group = "JavaScript"
languages = ["javascript"]
body = """
for (const item of items) {
}"""

[[snippet]]
group = "General"
name = "Hello"
body = "Hello!!!"
```

Each `[[snippet]]` becomes one line of the menu. The file is read every time the menu opens, so editing it takes effect immediately — no restart.

## Insert one

Open **Snippets** (`Alt-N`). Snippets sharing a `group` appear together in a submenu of that name; one with no group goes into **General**.

| Key | Effect |
| --- | --- |
| `Alt-N`, or `F10` then `→` to Snippets | Open the menu |
| `↑` `↓` | Move down the groups |
| `→`, or `Enter` | Open the highlighted group |
| `↑` `↓` then `Enter` | Insert the highlighted snippet |
| `←` | Back out of a group |
| `Escape` | Put the whole menu away |

The snippet goes in at the cursor. **Lines after the first are indented to match the line you inserted it on**, so a multi-line snippet dropped into a nested block lands where you would have typed it:

```
function main() {
  |                              ← cursor here
}
```

becomes, after **JavaScript ▸ for of**,

```
function main() {
  for (const item of items) {
  }
}
```

It is one undo step: `Ctrl-Z` takes the whole snippet back out.

## Keep snippets across every project

Put them in `~/.config/turbo-js/snippets.toml` — the same directory your own themes go in. Those appear in every project, and a project's own file adds to them rather than replacing them.

Where a project and you use the same `name` in the same `group`, **the project's wins**: it is the more specific statement of the two.

## Show a snippet only where it makes sense

Add `languages`, using the names the editor uses — `javascript`, `json`, `toml`, `yaml`, `markdown`, `html`, `xml`, `dockerfile`, `bash`:

```toml
[[snippet]]
name = "strict mode"
group = "Shell"
languages = ["bash"]
body = "set -euo pipefail"
```

That snippet then appears only when a shell script is the front window. Leave `languages` out and the snippet is offered everywhere, which is what you want for a licence header or a `TODO`.

A group left with nothing after filtering does not appear at all.

## Write a JavaScript body

Two habits, the first taken from the starter file:

- **Indent with two spaces.** It is what Prettier writes by default, so a tab in a body would be reformatted away the first time `npx prettier --write .` runs — a diff nobody asked for.
- **Use a literal string** — `'''…'''`, single quotes — for any body with a backslash in it. A JavaScript string carries `\n` and `\"` the way a Go string does, and in a TOML basic string (`"""…"""`) those escapes are resolved before the editor sees them: `console.log("caught: \"" + e + "\"")` would arrive with real quotation marks in it and no longer parse. Inside `'''` a backslash is just a backslash.

## Variants

- **You started the editor from a subdirectory.** The project's file is not found: only `./.turbo-js` is looked at, the same rule `settings.toml` follows. Your own snippets still appear.
- **The file has a mistake in it.** The menu shows a greyed-out `Cannot read snippets` where the groups would be, and **Create snippets file** is still there. Open the file and fix it.
- **You want a tab in a body.** In a basic string, write `\t` and TOML turns it into a tab when it reads the file. In a literal string, `\t` stays two characters — type the tab itself.

## See also

- Every key of the file and every rule: [Snippets reference](../reference/snippets.md)
- Why the menu is rebuilt each time it opens, why insertion re-indents, and why the JavaScript bodies indent two spaces: [Snippets](../explanation/snippets.md)
- The other file in `.turbo-js`: [Project settings](../reference/project-settings.md)