codesandbox-api

0.0.32 verified Sat Apr 25 auth: no javascript

Library for creating custom integrations and protocols with CodeSandbox, version 0.0.32 (stable, low release cadence). Provides APIs to communicate between sandbox frames and the editor, including protocol definitions, event handling, and utilities for building sandbox-level features. Differentiates from direct postMessage by offering typed abstractions and conventions. Ships TypeScript type definitions. Active development within the CodeSandbox monorepo.

Common errors

error Cannot find module 'codesandbox-api' ↓

cause Package is not installed or is missing from node_modules.

fix

Run: npm install codesandbox-api

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM import in a CommonJS environment without transpilation.

fix

Add "type": "module" to package.json, or use a bundler like webpack/rollup.

Warnings

deprecated Version 0.x is pre-1.0; APIs may break without major version bump. ↓

fix Pin to exact version and test upgrades; prefer latest 0.x patch.

gotcha Package contains minimal documentation; many exports are undocumented. ↓

fix Refer to source code or CodeSandbox client for usage examples; consider using source map.

gotcha ESM-only: No CommonJS build; using require() will not work. ↓

fix Use dynamic import() in Node or configure bundler for ESM.

gotcha Subpath exports: Some utilities are in dist/ subdirectories (e.g., actions). ↓

fix Import from specific subpath like 'codesandbox-api/dist/actions'.

Install

npm install codesandbox-api

yarn add codesandbox-api

pnpm add codesandbox-api

Imports

sandboxUrl
```
import { sandboxUrl } from 'codesandbox-api'
```
Main export for constructing sandbox URLs; ESM-only as no CJS bundle is provided in the package.

constructor

wrong

const { constructor } = require('codesandbox-api')

correct

import { constructor } from 'codesandbox-api'

Exports the internal 'constructor' function (unclear usage, likely a helper).

default
wrong
```
import { default } from 'codesandbox-api'
```
correct
```
import codesandbox from 'codesandbox-api'
```
Default export is the main module; named 'default' is not exported separately.
listen
```
import { listen } from 'codesandbox-api/dist/actions'
```
Some utilities are in subpath exports; check the dist folder for available actions.

Quickstart

Shows how to use the sandboxUrl function to create a CodeSandbox link from a GitHub repository.

import { sandboxUrl } from 'codesandbox-api';

// Generate a sandbox URL from a GitHub repo
const url = sandboxUrl({
  github: { repo: 'facebook/react', branch: 'main' },
  file: '/src/App.js'
});
console.log(url); // https://codesandbox.io/s/github/facebook/react/tree/main?file=/src/App.js