remark-sandpack

Use @lekoarts/remark-sandpack to more easily author Sandpack examples in your MDX. It parses individual code blocks and places them into Sandpack's files option. This way you don't have to write the JSX yourself.

[!NOTE] This package is a fork of thecuvii/remark-sandpack as the repository was put into read-only mode. @lekoarts/remark-sandpack is leaner, up-to-date, and maintained.

Installation

This package is ESM only.

npm install @lekoarts/remark-sandpack

Usage

Say your document index.mdx contains:

<Sandpack template="react">

```js name=App.js active
import { NAME } from './constants.js'

export default function App() {
  return <h1>Hello {NAME}</h1>
}
```

```js name=constants.js readOnly
export const NAME = 'World'
```

</Sandpack>

And the module index.mjs contains:

import remarkSandpack from '@lekoarts/remark-sandpack'
import { remark } from 'remark'
import remarkMdx from 'remark-mdx'
import { read } from 'to-vfile'

const file = await remark()
	.use(remarkMdx)
	.use(remarkSandpack)
	.process(await read('example.mdx'))

console.log(String(file))

Then running index.mjs yields:

<Sandpack template="react" files={{"App.js":{"code":"import { NAME } from './constants.js'\n\nexport default function App() {\n  return <h1>Hello {NAME}</h1>\n}","active":true},"constants.js":{"code":"export const NAME = 'World'","readOnly":true}}}>
  ```js name=App.js active
  import { NAME } from './constants.js'

  export default function App() {
    return <h1>Hello {NAME}</h1>
  }
  ```

  ```js name=constants.js readOnly
  export const NAME = 'World'
  ```
</Sandpack>

The individual code blocks are added to the files prop of the <Sandpack> component. Any other props will be passed through to the <Sandpack> component, e.g. in the example above the template="react" is kept in place.

Code blocks

You are required to add a name to each code block.

```js name=filename.js
console.log('Hello World')
```

You can also add optional configuration for each code block (Sandpack's file format).

• hidden
• active
• readOnly
• showReadOnly

Add them after the filename like so:

```js name=filename.js active
console.log('Hello World')
```

API

This package exports no identifiers. The default export is remarkSandpack.

unified().use(remarkSandpack[, options])

Add support for transforming code blocks into files prop for <Sandpack> components.

Parameters

• options (Options, optional) — configuration

Returns

Nothing (undefined).

Notes

Doesn't handle adding Sandpack to your app and into your MDX. Follow the Sandpack install instructions to add Sandpack. You'll need to pass/import that component into your MDX.

Options

Configuration (TypeScript type)

Fields

• componentName (Array<string>, default: ['Sandpack']) — By default, @lekoarts/remark-sandpack looks for <Sandpack> occurences in the MDX. If you use a different name, adjust componentName. You can also pass in multiple names in case you have different Sandpack components.

Examples

Custom componentName

This example overrides the default componentName in order to use a different name in the MDX.

import remarkSandpack from '@lekoarts/remark-sandpack'
import { remark } from 'remark'
import remarkMdx from 'remark-mdx'
import { read } from 'to-vfile'

const file = await remark()
	.use(remarkMdx)
	.use(remarkSandpack, { componentName: ['Playground'] })
	.process(await read('example.mdx'))

console.log(String(file))

<Playground template="vanilla">

```js name=index.js active
console.log('Hello World')
```

</Playground>

Astro

You can view a full end-to-end example inside examples/astro.