# Twoslash

Twoslash shows the types of a code block as your editor does: TypeScript checks the code when the page compiles, and a popup shows the type and the docs of each name. Hover the names below:

```ts twoslash
import { useColorMode } from "vuesho/client";

const { preference, isDark } = useColorMode();
```

## Setup

<Steps>
<Step>

### Install the Packages

```npm
npm i -D twoslash-vue typescript@6
```

`twoslash-vue` is Twoslash with Vue components. It runs on the JavaScript API of TypeScript 5.5 to 6, which TypeScript 7 doesn't have.

</Step>
<Step>

### Add the Transformer

`transformerTwoslash()` of `vuesho/twoslash` transforms the code blocks of your pages. Add it to the Vite plugin:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { transformerTwoslash } from "vuesho/twoslash";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho({ markdown: { highlight: { transformers: [transformerTwoslash()] } } })],
});
```

A collection with its own [`markdown`](/content#compile-options) option compiles with those options, so add the transformer there too.

</Step>
<Step>

### Import the Stylesheet

Import the styles of the popups after your color preset:

```css title="src/theme.css"
@import "vuesho/style/neutral.css";
@import "vuesho/style/twoslash.css";
```

With [Tailwind CSS](/theme#tailwind-css), import the source of the styles, `vuesho/css/twoslash.css`, instead.

</Step>
</Steps>

Then add `twoslash` after the language of a code block:

````md
```ts twoslash
const greeting = "Hello";
```
````

Code blocks of `ts`, `tsx`, `js`, `jsx`, `json` and `vue` can use Twoslash. TypeScript resolves an import from the root of your project, so a code block can import the packages your site installs, like `vuesho/client` above.

## Notations

Comments in a code block tell Twoslash what to show, and the output leaves them out:

- `// ^?` under a name shows its type below the line.
- `// ^|` under the end of a name shows the completions there.
- `// ^^^` under a part of a line highlights it.
- `// @log: text` adds a note under the next line, and so do `@warn`, `@error` and `@annotate` in their colors.
- `// ---cut---` hides the code above it, which still counts for the types.
- `// @filename: other.ts` starts another file, which the other files can import.
- `// @strict: false` sets a compiler option, like any option of `tsconfig.json`.
- `// @showEmit` shows the JavaScript that TypeScript emits, in place of the code.

The [reference of Twoslash](https://twoslash.netlify.app/refs/notations) describes them all.

```ts twoslash tab="Output"
// @noErrors
import { withBase } from "vuesho/client";

// @log: The base path of the site, then the path
const href = withBase("/guide");
//    ^?
href.toUpperCase();
//   ^^^^^^^^^^^
href.slic;
//       ^|
```

````md tab="Markdown"
```ts twoslash
// @noErrors
import { withBase } from "vuesho/client";

// @log: The base path of the site, then the path
const href = withBase("/guide");
//    ^?
href.toUpperCase();
//   ^^^^^^^^^^^
href.slic;
//       ^|
```
````

### Errors

A type error that a code block doesn't expect fails the build, at the line of the code block, with the message of TypeScript. To show an error, list its code in `// @errors`:

```ts twoslash tab="Output"
// @errors: 2322
const count: number = "one";
```

````md tab="Markdown"
```ts twoslash
// @errors: 2322
const count: number = "one";
```
````

`// @noErrors` hides every error, for code that is incomplete on purpose, like the completion above.

### Reusing Code

A code block with `include setup` after its language saves its code as `setup`, and `// @include: setup` inserts that code in a later block of the page. A line `// - part` in the saved block names the code above it, which `// @include: setup-part` inserts alone:

````md
```ts twoslash include setup
const user = { name: "Alice" };
// - user
const admin = { ...user, role: "admin" };
```

```ts twoslash
// @include: setup-user
// ---cut---
user.name;
```
````

## Vue Components

A code block of `vue` is a component: Twoslash reads its `<script setup>` and its template, with the types that the tools of Vue give them.

```vue twoslash tab="Output"
<script setup lang="ts">
import { useColorMode } from "vuesho/client";

const { isDark } = useColorMode();
</script>

<template>
  <p v-if="isDark">The page is dark.</p>
</template>
```

````md tab="Markdown"
```vue twoslash
<script setup lang="ts">
import { useColorMode } from "vuesho/client";

const { isDark } = useColorMode();
</script>

<template>
  <p v-if="isDark">The page is dark.</p>
</template>
```
````

A code block of `tsx` or `jsx` uses the JSX of Vue.

## Options

`transformerTwoslash()` takes options:

- `explicitTrigger`: `false` runs Twoslash on every code block of its languages, and a block with `no-twoslash` after its language opts out.
- `langs`: the languages that can use Twoslash.
- `twoslashOptions`: the options of Twoslash, like `compilerOptions` and `vueCompilerOptions`. Modules resolve as in a project of Vite by default.
- `jsdoc`: `false` leaves the docs of a name out of its popup.
- `throws`: `false` shows a code block without types when it fails, in place of failing the build.

## Cache

TypeScript starts in about 0.3 s, then takes a few milliseconds for each code block, and longer for a block that imports a large package. `createFileSystemTypesCache()` keeps the types of each block in `node_modules/.vuesho/twoslash`, so the next build or dev server reads them:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { createFileSystemTypesCache, transformerTwoslash } from "vuesho/twoslash";
import vuesho from "vuesho/vite";

const twoslash = transformerTwoslash({ typesCache: createFileSystemTypesCache() });

export default defineConfig({
  plugins: [vuesho({ markdown: { highlight: { transformers: [twoslash] } } })],
});
```

A change of the code of a block, its language or the options resolves its types again. An update of a package that a block imports doesn't, so delete the folder after updating one.

## Popup Components

The popups are the components `Popup`, `PopupTrigger` and `PopupContent` of the [components module](/markdown#your-own-components), which `vuesho/components` exports. A `src/components.ts` that doesn't re-export `vuesho/components` must export them, or a code block of Twoslash fails at its line. To change the popups, export your own components with those names.
