DOCSEARCHbyAlgolia
Submit Docs

vitepress-plugin-sandpack

website·Indexed 31 days ago

https://vitepress-sandbox.js-bridge.com

A plugin for VitePress that integrates Sandpack to create live-running code editing experiences. It supports multiple languages and frameworks including Angular, React, React-TS, Vanilla, Vanilla-TS, Vue, Vue3, Vue3-TS, Svelte, and Solid. Features include custom file content, snippet support, theme customization (including dark mode), and RTL layout support.

Tokens
4.6K
Snippets
36
Records
42
Agent score
55%

What's inside vitepress-plugin-sandpack

  1. Overview of vitepress-plugin-sandpack

    vitepress-plugin-sandpack allows you to use Sandpack components as directives within VitePress markdown files. It provides editable sandboxes that run in the browser, powered by the CodeSandbox online bundler. It supports various templates including: static, angular, react, react-ts, vanilla, vanilla-ts, vue, vue3, vue3-ts, svelte, solid, and test-ts.

  3. Implement a basic Vue 3 component using Vite

    For projects using the vite-vue template (Vue version >= 3.2.0), you can use the <script setup> syntax to define reactive state and render it in the template. This example demonstrates a simple component that uses a reactive reference to display a greeting.
    <script setup>
import { ref } from "vue";

const data = ref("world");
</script>

<template>
  <h1>Hello {{ data }}</h1>
</template>

<style>
h1 {
  font-size: 1.5rem;
}
</style>

  4. Implement a basic Vue 3 component with TypeScript in Vite

    When using the vite-vue-ts template (compatible with Vue version >= 3.2.0), you can use <script setup lang="ts"> to define reactive state with TypeScript generics. This allows for type-safe references using the ref function.
    <script setup lang="ts">
import { ref } from "vue";

const data = ref<string>("world");
</script>

<template>
  <h1>Hello {{ data }}</h1>
</template>

<style>
h1 {
  font-size: 1.5rem;
}
</style>

  5. Install vitepress-plugin-sandpack

    Install the vitepress-plugin-sandpack package as a development dependency in your VitePress project folder. If you are using pnpm, you must also install markdown-it-container.
    cd vitepress-project-folder
npm i vitepress-plugin-sandpack -D

# If using pnpm:
pnpm add markdown-it-container -D

  6. Create a custom Sandbox component to override default options

    To customize default sandbox behaviors such as showLineNumbers, resizablePanels, and closableTabs, create a wrapper component that extends Sandbox from vitepress-plugin-sandpack. Using TSX is recommended for simplicity, though Vue SFC is also supported.
    // OptsSandbox.tsx
import { defineComponent } from 'vue';
import { Sandbox, sandboxProps } from 'vitepress-plugin-sandpack';

export const OptsSandbox = defineComponent({
  name: 'OptsSandbox',
  props: sandboxProps,
  setup(props, { slots }) {
    return () => (
      <Sandbox
        {...props}
        options={{
          showLineNumbers: true,
          resizablePanels: false,
          closableTabs: true,
        }}
      >
        { slots?.default ? slots.default() : null }
      </Sandbox>
    );
  },
});

  7. Resolve ESM import errors in VitePress config

    Because vitepress-plugin-sandpack is an ESM-only package, attempting to load it via require in a CommonJS environment will result in a 'Failed to resolve' error. To fix this, convert your VitePress configuration to ESM using one of the following methods:

    1. Add "type": "module" to the nearest package.json file.
    2. Rename your configuration file from docs/.vitepress/config.js (or .ts) to docs/.vitepress/config.mjs (or .mts).

  8. Configure a custom entry file

    You can change the entry file path to a custom location (e.g., moving it from /src/main.ts to a root directory file like /myEntry.js).

    Caveat: When changing the entry file path, you must manually ensure all required files are included in the bundle process, as pre-existing template settings may no longer apply. For example, if you move a component from /MyApp.vue to /src/MyApp.vue, you must update the import paths accordingly.

  9. Control sandbox code execution and autorun

    The autorun option determines if the code executes automatically. If set to false, the user must manually click the run button in the editor area to execute the code.
    {
  autorun: false // Default: true. Requires manual click of the run button.
}

  10. Set files to read-only in the sandbox

    The readOnly option can be applied globally to all files or specifically to individual files. Use showReadOnly to toggle the visibility of the read-only label on those files.
    {
  readOnly: false,    // Default: false. Set to true for global read-only mode.
  showReadOnly: true   // Default: true. Shows the read-only label of the file.
}

  11. Configure VitePress Sandbox editor and preview visibility

    Use these options to control the visibility and dimensions of the sandbox editor and preview areas.
    {
  hideEditor: false,      // Default: false. Hides the editor area.
  coderHeight: undefined, // Default: undefined. Sets the height of the editor.
  previewHeight: undefined // Default: undefined. Sets the height of the preview area.
}

  12. Configure sandbox UI elements and navigation

    Manage the visibility of various UI components such as the navigator, line numbers, and refresh buttons.
    {
  showNavigator: false,      // Default: false. Shows the navigator.
  showLineNumbers: false,     // Default: false. Shows line numbers in the editor.
  wrapContent: false,         // Default: false. Wraps content in the editor.
  showRefreshButton: true,    // Default: true. Shows the refresh button (disabled if showNavigator is true).
  showTabs: true,             // Default: true. Shows file tabs.
  closableTabs: false         // Default: false. Shows the close icon on tabs.
}