Code Snippets
Code Snippets in Vocs come in two forms:
- a virtual file snippet in your Markdown code (Virtual File Snippets), or
- a physical file snippet in your file system (Physical File Snippets)
We will show you both approaches below.
Virtual File Snippets
Create the code snippet
We will create a virtual file snippet called example.ts
. We can define a virtual file in markdown using the filename="example.ts"
meta tag.
```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
```
Import the snippet
Next, we will import the snippet into our Markdown file using the // [!include ...]
marker.
#### Create your Client
```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
```
#### Use Actions
```ts
// [!include example.ts]
const blockNumber = await client.getBlockNumber() // [!code focus]
```
Output
The resulting output will look like this:
Create your Client
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
Use Actions
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
Physical File Snippets
Create the code snippet
We will create a physical file snippet called example.ts
. Let's put this under a snippets/
directory in your codebase.
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
Import the snippet
Next, we will import the snippet into our Markdown file using the // [!include ...]
marker.
#### Create your Client
```ts
// [!include ~/snippets/example.ts]
```
#### Use Actions
```ts
// [!include ~/snippets/example.ts]
const blockNumber = await client.getBlockNumber() // [!code focus]
```
Output
The resulting output will look like this:
Create your Client
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
Use Actions
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
Regions
You can also include a specific region of a code snippet by using the // [!region]
and // [!endregion]
markers.
// [!region import]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
// [!endregion import]
// [!region setup]
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
// [!endregion setup]
// [!region usage]
const blockNumber = await client.getBlockNumber()
// [!endregion usage]
Then, we can include the regions in the Markdown with the // [!include]
marker:
```ts
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts:import]
// [!include ~/snippets/example.ts:setup]
// [!include ~/snippets/example.ts:usage]
writeFileSync('test.txt', blockNumber.toString())
```
Which will result in the snippet being rendered like this:
import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
writeFileSync('test.txt', blockNumber.toString())
Duplicate variable declarations
When writing snippets, you may run into a scenario where you want to define multiple regions that share the same variable name.
To avoid type errors, you can use the _$
suffix to discriminate the variable name.
The rendered snippet will still use the original variable name (ie. the name before the _$
suffix).
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const block_$1 = await client.getBlock()
const block_$2 = await client.getBlock({ blockNumber: 42069n })
const block_$3 = await client.getBlock({ blockTag: 'latest' })
Find and Replace
You can use /(find)/(replace)/
syntax to find and replace text in the snippet.
```ts
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts /viem/@viem\/core/ /mainnet/sepolia/]
writeFileSync('test.txt', blockNumber.toString())
```
Which will result in the snippet being rendered like this:
import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from '@viem/core'
import { sepolia } from '@viem/core/chains'
const client = createPublicClient({
chain: sepolia,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
writeFileSync('test.txt', blockNumber.toString())
Tip: Code Block Markers
We can also include markers like line highlight (// [!code hl]
) in our code snippets.
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber() // [!code hl]
Which will result in the snippet being rendered like this:
import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
writeFileSync('test.txt', blockNumber.toString())
Tip: Twoslash
We can also include Twoslash markers in our code snippets.
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const blockNumber = await client.getBlockNumber()
// ^?
Which will result in the snippet being rendered like this:
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
const client = createPublicClient({
chain: mainnet,
transport: http(),
})
const const blockNumber: bigintblockNumber = await client.getBlockNumber()
Tip: Twoslash + Virtual Files
We can also use virtual files with Twoslash code blocks.
:::code-group
```ts twoslash [example.ts]
import { client } from './client.js'
const blockNumber = await client.getBlockNumber()
```
```ts twoslash [client.ts] filename="client.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
export const client = createPublicClient({
chain: mainnet,
transport: http(),
})
```
:::
Which will result in the snippet being rendered like this:
import { client } from './client.js'
const blockNumber = await client.getBlockNumber()