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@6twoslash-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:
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:
@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: textadds a note under the next line, and so do@warn,@errorand@annotatein their colors.// ---cut---hides the code above it, which still counts for the types.// @filename: other.tsstarts another file, which the other files can import.// @strict: falsesets a compiler option, like any option oftsconfig.json.// @showEmitshows the JavaScript that TypeScript emits, in place of the code.
The reference of Twoslash describes them all.
import { } from "vuesho/client";
const href = ("/guide");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";// @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:falseruns Twoslash on every code block of its languages, and a block withno-twoslashafter its language opts out.langs: the languages that can use Twoslash.twoslashOptions: the options of Twoslash, likecompilerOptionsandvueCompilerOptions. Modules resolve as in a project of Vite by default.jsdoc:falseleaves the docs of a name out of its popup.throws:falseshows 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:
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, 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.