https://github.com/antfu/nuxt-content-twoslash

TwoSlash integrations for Nuxt Content
https://github.com/antfu/nuxt-content-twoslash

Last synced: 14 days ago
JSON representation

TwoSlash integrations for Nuxt Content

• Host: GitHub
• URL: https://github.com/antfu/nuxt-content-twoslash
• Owner: antfu
• License: mit
• Created: 2024-02-12T14:52:58.000Z (9 months ago)
• Default Branch: main
• Last Pushed: 2024-08-05T16:12:18.000Z (3 months ago)
• Last Synced: 2024-10-16T21:10:16.386Z (28 days ago)
• Language: TypeScript
• Homepage:
• Size: 1.26 MB
• Stars: 46
• Watchers: 2
• Forks: 6
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

        
# nuxt-content-twoslash

[TwoSlash](https://github.com/twoslashes/twoslash) integrations for Nuxt Content.

## Installation

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

```bash

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

```ts

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

````md

```ts twoslash

import { ref } from 'vue'

const message = ref('Hello')

```

```vue twoslash

import { ref } from 'vue'

// Reactive state.

const count = ref(0)

  Count is: {{ count }}

```

````

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](https://github.com/nuxt/nuxt.com), we load the docs externally from [nuxt/nuxt](https://github.com/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](https://github.com/nuxt/nuxt) are type safe, we use this CLI in the CI to [verify the code snippets](https://github.com/nuxt/nuxt/blob/7815aa534edb0e7dbf7a6c4d43dccc11acb408df/package.json#L33).