Skip to Content
Vuesho

Twoslash

The types of TypeScript and Vue code in popups.

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:

import {  } from "vuesho/client";

const { ,  } = ();

Setup

Install the Packages

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.

Add the Transformer

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

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 option compiles with those options, so add the transformer there too.

Import the Stylesheet

Import the styles of the popups after your color preset:

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

With Tailwind CSS, import the source of the styles, vuesho/css/twoslash.css, instead.

Then add twoslash after the language of a code block:

```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 describes them all.

import {  } from "vuesho/client";

const href = ("/guide");
const href: string
The base path of the site, then the path
.(); .slic
  • slice
;

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:

const count: number = "one";
Type 'string' is not assignable to type 'number'.

// @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:

```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.

<script setup lang="ts">
import {  } from "vuesho/client";

const {  } = ();
</script>

<template>
  < v-if="">The page is dark.</>
</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:

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.

The popups are the components Popup, PopupTrigger and PopupContent of the components module, 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.