gjssss/nuxt-content-twoslash

TwoSlash integrations for Nuxt Content

nuxt-content-twoslash

TwoSlash integrations for Nuxt Content.

Installation

1. Install the nuxt-content-twoslash module to your project:

pnpm add nuxt-content-twoslash
#
yarn add nuxt-content-twoslash
#
npm install nuxt-content-twoslash

2. Add it to your 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: {
    // ...
  }
})

Usage

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')
```

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

How it works

Nuxt Content uses Shiki under the hood via the Nuxt MDC module. This module injects a Shiki transformer based on @shikijs/twoslash to leverage Twoslash (which invokes a TypeScript 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.

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.