Setup

Setting up Karagöz Sandbox is straightforward. Simply follow the steps below.

Installation

Install the following packages using your preferred package manager.

# NPM
npm install --save @karagoz/sandbox @karagoz/shared

# PNPM
pnpm add @karagoz/sandbox @karagoz/shared

# Yarn
yarn add @karagoz/sandbox @karagoz/shared

# Bun
bun add @karagoz/sandbox @karagoz/shared

Cross-Origin Isolation

The WebContainer API documentation states:

WebContainers require SharedArrayBuffer, which, in turn, requires the website where they are running to be cross-origin isolated. Because of that, you'll need to set COOP/COEP headers:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

To learn more about this topic, you can check Configuring Headers in the WebContainer API docs.

To configure your development server, apply these adjustments:

Vue.js Project

Add the following in your Vite config:

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
})

Nuxt Project

Add the following to your Nuxt config:

export default defineNuxtConfig({
  routeRules: {
    '/*': {
      headers: {
        'Cross-Origin-Embedder-Policy': 'require-corp',
        'Cross-Origin-Opener-Policy': 'same-origin',
      },
    },
  },
  hooks: {
    // routeRules should be enough to get things running, but without the following Nuxt DevTools won't work.
    'vite:serverCreated': (server) => {
      server.middlewares.use((_req, res, next) => {
        res.setHeader('Cross-Origin-Resource-Policy', 'same-origin')
        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
        res.setHeader('Access-Control-Allow-Origin', 'https://localhost:3000')
        next()
      })
    },
  },
})

Styles

After installation, you will need to import the styles.

The can be done for example in your entry as follows:

/* main.ts */
import '@karagoz/shared/dist/karagoz-shared.css'
import '@karagoz/sandbox/dist/karagoz-sandbox.css'

Or in the main stylesheet:

/* main.css */
@import "@karagoz/shared/dist/karagoz-shared.css";
@import "@karagoz/sandbox/dist/karagoz-sandbox.css";

I18N

Karagöz Sandbox uses vue-i18n to provide a localised interface. It comes with translations for Arabic, English and German out-of-the-box, but there are only a few strings to translate, so you can easily support your language.

/* main.ts */

import { createApp } from 'vue'
import App from './App.vue'
import { createI18n } from 'vue-i18n'
import { i18nMessages } from '@karagoz/sandbox'

const i18n = createI18n({
  locale: 'en',
  messages: { 
    /* Already supported languages */ 
    ar: { ...i18nMessages.ar },
    de: { ...i18nMessages.de },
    en: { ...i18nMessages.en },
    /* Additional language */
    fr: {
      /* All Karagöz translations are under the krgz key/prefix. */
      krgz: {
        /* ... */
      }
    }
  }
})

createApp(App).use(i18n).mount('#app')

If you want type-safety and to avoid missing translations, you can augment vue-i18n as follows:

/* vue-i18n.d.ts */

import { i18nMessages } from '@karagoz/sandbox'

type MessageSchema = typeof i18nMessages.en

/**
 * Provide type intellisense for translation keys and date/number formats.
 */
declare module 'vue-i18n' {
  // define the locale messages schema
  export interface DefineLocaleMessage extends MessageSchema {}
}

That concludes the setup. Now you can start create your first sandbox :)