Skip to content

Commit d81d2a5

Browse files
ghostwriternrghostwriternr
authored
Implement code interpreter API (#49)
* feat: implement code interpreter with Jupyter kernel integration - Add Jupyter (Python) and TSLab (JavaScript/TypeScript) kernel support - Implement streaming code execution with rich MIME type outputs - Support charts, tables, images, and structured data rendering - Add CodeInterpreter class with context management - Create notebook-style UI in React example app * Fix example * Use better kernel for JS * Remove comment * Use crypto to generate session ID * Add changeset * Remove unused types * Fix lint errors * Fix build failures
1 parent b706463 commit d81d2a5

24 files changed

+4093
-247
lines changed

‎.changeset/proud-turkeys-enjoy.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@cloudflare/sandbox": patch
3+
---
4+
5+
Implement code interpreter API

‎.github/workflows/prerelease.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ jobs:
2020
node-version: 20
2121
cache: "npm"
2222

23+
- uses: oven-sh/setup-bun@v2
24+
with:
25+
bun-version: latest
26+
2327
- run: npm install
2428

2529
- name: Modify package.json version
@@ -29,6 +33,11 @@ jobs:
2933
run: npx tsx .github/resolve-workspace-versions.ts
3034

3135
- run: npm run build
36+
37+
# Install container dependencies before type checking
38+
- name: Install container dependencies
39+
run: cd packages/sandbox/container_src && bun install
40+
3241
- run: npm run check
3342
- run: CI=true npm run test
3443

‎.github/workflows/pullrequest.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,16 @@ jobs:
2323
node-version: 20
2424
cache: "npm"
2525

26+
- uses: oven-sh/setup-bun@v2
27+
with:
28+
bun-version: latest
29+
2630
- run: npm install
2731
- run: npm run build
32+
33+
# Install container dependencies before type checking
34+
- name: Install container dependencies
35+
run: cd packages/sandbox/container_src && bun install
36+
2837
- run: npm run check
2938
- run: CI=true npm run test

‎CONTRIBUTING.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Contributing to Cloudflare Sandbox SDK
2+
3+
Thank you for your interest in contributing to the Cloudflare Sandbox SDK! This guide will help you get started with development.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Node.js 18+ and npm
10+
- Docker (for container development)
11+
- Bun (install from https://bun.sh)
12+
- A Cloudflare account (for testing in production)
13+
14+
### Initial Setup
15+
16+
1. **Clone the repository**
17+
```bash
18+
git clone https://github.com/cloudflare/sandbox-sdk
19+
cd sandbox-sdk
20+
```
21+
22+
2. **Install dependencies**
23+
```bash
24+
npm install
25+
```
26+
27+
3. **Install container dependencies**
28+
29+
The container source has its own dependencies that need to be installed for TypeScript checking:
30+
```bash
31+
cd packages/sandbox/container_src && bun install && cd -
32+
```
33+
34+
> **Note**: This step is required for TypeScript to properly check the container source files. Without it, you'll see errors about missing modules like `@jupyterlab/services` and `uuid`.
35+
36+
4. **Build the project**
37+
```bash
38+
npm run build
39+
```
40+
41+
5. **Run type checking and linting**
42+
```bash
43+
npm run check
44+
```
45+
46+
### Project Structure
47+
48+
```
49+
sandbox-sdk/
50+
├── packages/
51+
│ └── sandbox/ # Main SDK package
52+
│ ├── src/ # SDK source code
53+
│ ├── container_src/ # Container runtime code (uses Bun)
54+
│ └── Dockerfile # Container image definition
55+
├── examples/
56+
│ └── basic/ # Example implementation
57+
├── scripts/ # Build and development scripts
58+
└── package.json # Workspace configuration
59+
```
60+
61+
### Development Workflow
62+
63+
1. **Making Changes**
64+
- The SDK code is in `packages/sandbox/src/`
65+
- Container runtime code is in `packages/sandbox/container_src/`
66+
- Example code is in `examples/basic/`
67+
68+
2. **Running Tests**
69+
```bash
70+
npm test
71+
```
72+
73+
3. **Type Checking**
74+
```bash
75+
npm run typecheck
76+
```
77+
78+
4. **Linting**
79+
```bash
80+
npm run check
81+
```
82+
83+
5. **Building**
84+
```bash
85+
npm run build
86+
```
87+
88+
### Testing Locally
89+
90+
To test the SDK locally with the example (ensure you've completed the development setup):
91+
92+
1. **Navigate to the example directory**
93+
```bash
94+
cd examples/basic
95+
```
96+
97+
2. **Install dependencies**
98+
```bash
99+
npm install
100+
```
101+
102+
3. **Start the development server**
103+
```bash
104+
npm start
105+
```
106+
107+
4. **Open your browser**
108+
Navigate to the URL shown in the terminal (typically `http://localhost:8787`)
109+
110+
### Container Development
111+
112+
The container source (`container_src/`) uses Bun as its runtime and has separate dependencies:
113+
114+
- Uses `bun.lock` for dependency management
115+
- Requires `bun install` for installing dependencies
116+
- Dependencies are installed inside Docker during build, but also needed locally for TypeScript
117+
118+
### Common Issues
119+
120+
1. **TypeScript errors about missing modules**
121+
- Make sure you've run `cd packages/sandbox/container_src && bun install`
122+
- This installs the container dependencies needed for type checking
123+
124+
2. **Port exposure errors in local development**
125+
- Ensure your Dockerfile includes `EXPOSE` directives for required ports
126+
- See the README for details on local development port requirements
127+
128+
3. **Build failures**
129+
- Run `npm run clean` to clear build artifacts
130+
- Ensure Docker is running for container builds
131+
132+
### Submitting Changes
133+
134+
1. **Create a feature branch**
135+
```bash
136+
git checkout -b feature/your-feature-name
137+
```
138+
139+
2. **Make your changes**
140+
- Write clear, concise commit messages
141+
- Add tests for new functionality
142+
- Update documentation as needed
143+
144+
3. **Run all checks**
145+
```bash
146+
npm run check
147+
npm test
148+
```
149+
150+
4. **Submit a pull request**
151+
- Provide a clear description of your changes
152+
- Reference any related issues
153+
- Ensure all CI checks pass
154+
155+
### Code Style
156+
157+
- We use TypeScript for all code
158+
- Follow the existing code style (enforced by Biome)
159+
- Use meaningful variable and function names
160+
- Add JSDoc comments for public APIs
161+
162+
### Questions?
163+
164+
If you have questions or need help:
165+
- Open an issue on GitHub
166+
- Join our [Discord community](https://discord.gg/cloudflaredev)
167+
- Check existing issues and pull requests
168+
169+
Thank you for contributing!

0 commit comments

Comments
 (0)