TwoSlash integrations for Nuxt Content.
nuxt-content-twoslash
module to your project:pnpm add nuxt-content-twoslash
#
yarn add nuxt-content-twoslash
#
npm install nuxt-content-twoslash
modules
section in your nuxt.config
, before @nuxt/content
:// nuxt.config.js
export default defineNuxtConfig({
modules: [
'nuxt-content-twoslash', // this needs to be before `@nuxt/content`
'@nuxt/content'
],
content: {
// ...
},
twoslash: {
// ...
}
})
To start using Twoslash in your Nuxt Content markdown files, you will need to add twoslash
within your markdown code block tag.
Try out the below code snippet and watch the magic happen.
```ts twoslash
import { ref } from 'vue'
const message = ref('Hello')
<script setup>
import { ref } from 'vue'
// Reactive state.
const count = ref(0)
</script>
<template>
<button>Count is: {{ count }}</button>
</template>
For more advanced usage, please see the [Twoslash Notations](https://twoslash.netlify.app/refs/notations).
## How it works
[Nuxt Content](https://github.com/nuxt/content) uses [Shiki](https://github.com/shikijs/shiki) under the hood via the [Nuxt MDC module](https://github.com/nuxt-modules/mdc). This module injects a Shiki transformer based on [`@shikijs/twoslash`](https://shiki.style/packages/twoslash) to leverage [Twoslash](https://github.com/twoslashes/twoslash) (which invokes a [TypeScript](https://www.typescriptlang.org/) server) to get the type information while also validating the type safety.
With Nuxt Content's cache mechanism, Twoslash will run only once at build time and pre-render phrase. The generated type information will be served as static content and shipped with your app. So there would be no runtime overhead.
## Nuxt Specific Types
By default, this module will try to read the types generated by Nuxt and the `tsconfig.json` under `.nuxt` directory and inject them into TwoSlash context. Ideally this would make your code snippets works behave closer to your local dev environment.
If you don't want this behavior, you can disable it by setting `twoslash.injectNuxtTypes` to `false` in the module options.
## CLI Usage
This module also provides a command-line interface to verify TwoSlash code snippets in your markdown files, where you can guard the type safety in continuous integration.
```bash
npx nuxt-content-twoslash verify
[!TIP] An example usage is that in nuxt/nuxt.com, we load the docs externally from nuxt/nuxt repository. This way it allows the docs to be closer to the source code and easier for contributors to update them in the same PR. To support that seperation while able to make sure code snippets in nuxt/nuxt are type safe, we use this CLI in the CI to verify the code snippets.