Skip to content

Commit b3012d5

Browse files
yuri91yuri91
committed
WIP browserpod docs
1 parent 6d2a90f commit b3012d5

File tree

19 files changed

+438
-0
lines changed

19 files changed

+438
-0
lines changed

‎packages/astro-theme/layouts/DocsArticle.astro‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ function getEditHref(id: string): string {
4242
if (Astro.site?.hostname === "cheerp.io") site = "cheerp";
4343
if (Astro.site?.hostname === "cheerpj.com") site = "cheerpj";
4444
if (Astro.site?.hostname === "cheerpx.io") site = "cheerpx";
45+
if (Astro.site?.hostname === "browserpod.io") site = "browserpod";
4546
if (!site) throw new Error("unable to derive site dirname from Astro.site");
4647
return `https://github.com/leaningtech/labs/edit/main/sites/${site}/src/content/docs/${id}`;
4748
}

‎packages/astro-theme/lib/products.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,19 @@ export const products: { [product in Product]: ProductData } = {
130130
github: "https://github.com/leaningtech/cheerpx-games-runner",
131131
repositoryName: "cheerpx-games-runner",
132132
},
133+
browserpod: {
134+
id: "browserpod",
135+
type: "technology",
136+
name: "browserpod",
137+
href: "https://browserpod.io",
138+
logotype: cheerpjLogotype,
139+
favicon: baseWithSlash + "cheerpj3/favicon.ico",
140+
subtitle: "Java Virtual Machine for modern web browsers",
141+
description:
142+
"Run Java 8, 11 and 17 applications, libraries, applets, Java Web Start, and Oracle Forms on the web without legacy plugins.",
143+
github: "https://github.com/leaningtech/browserpod-meta",
144+
repositoryName: "browserpod-meta",
145+
},
133146
};
134147

135148
export function productFromUrl(url: URL): ProductData | undefined {
@@ -141,6 +154,8 @@ export function productFromUrl(url: URL): ProductData | undefined {
141154
return products.cheerpj3;
142155
case "https://cheerpx.io":
143156
return products.cheerpx;
157+
case "https://browserpod.io":
158+
return products.browserpod;
144159
}
145160

146161
// Fallback for labs

‎sites/browserpod/astro.config.mjs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { defineConfig } from "astro/config";
2+
import theme from "@leaningtech/astro-theme";
3+
import { resolve } from "node:path";
4+
5+
// https://astro.build/config
6+
export default defineConfig({
7+
site: "https://browserpod.io",
8+
base: "/docs",
9+
integrations: [
10+
theme({
11+
baseIsDocs: true,
12+
}),
13+
],
14+
vite: {
15+
resolve: {
16+
alias: [
17+
{
18+
find: "@",
19+
replacement: resolve("./src/"),
20+
},
21+
],
22+
},
23+
},
24+
});

‎sites/browserpod/package.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "@leaningtech/browserpod-io",
3+
"private": true,
4+
"type": "module",
5+
"version": "0.0.1",
6+
"scripts": {
7+
"dev": "astro dev",
8+
"start": "astro dev",
9+
"build": "astro build",
10+
"preview": "astro preview",
11+
"astro": "astro"
12+
},
13+
"dependencies": {
14+
"@astrojs/check": "^0.7.0",
15+
"@astrojs/svelte": "^5.6.0",
16+
"@astrojs/tailwind": "^5.1.0",
17+
"@leaningtech/astro-theme": "workspace:^",
18+
"@leaningtech/cheerp-ts-three-demo": "workspace:^",
19+
"astro": "^4.5.18",
20+
"astro-icon": "^0.8.1",
21+
"svelte": "^4.2.18",
22+
"tailwindcss": "^3.4.4",
23+
"typescript": "^5.5.3"
24+
}
25+
}

‎sites/browserpod/src/consts.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
// TODO: make discordbutton component
2+
export { DISCORD_URL } from "@leaningtech/astro-theme/consts";

‎sites/browserpod/src/content/config.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import { defineCommonCollections } from "@leaningtech/astro-theme/content";
2+
3+
export const collections = defineCommonCollections();

‎sites/browserpod/src/content/docs/00-overview.mdx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: BrowserPod
3+
shortTitle: Overview
4+
description: Run Dev Environments in your browser
5+
---
6+
7+
import LinkButton from "@leaningtech/astro-theme/components/LinkButton.astro";
8+
import { DISCORD_URL } from "@/consts.ts";
9+
10+
<div class="not-prose flex gap-2 mb-2">
11+
<img
12+
src="https://img.shields.io/badge/version-0.1-orange"
13+
alt="Version 0.1"
14+
/>
15+
<a href="https://discord.leaningtech.com/">
16+
<img
17+
src="https://img.shields.io/discord/988743885121548329?color=%237289DA&logo=discord&logoColor=ffffff"
18+
alt="Discord server"
19+
/>
20+
</a>
21+
<a href="https://github.com/leaningtech/browserpod-meta/issues">
22+
<img
23+
src="https://img.shields.io/github/issues/leaningtech/browserpod-meta.svg?logo=github"
24+
alt="GitHub issues"
25+
/>
26+
</a>
27+
</div>
28+
29+
<div class="text-lg">
30+
Instant, in-browser runtime for Node.js, Python, and Ruby on Rails to power the future of Web-based developer experiences.
31+
32+
Run Node.js projects in your browser, unmodified (Python, Ruby, and more coming in the future).
33+
34+
Access the local http server in the same page or from another tab to view, test, and iterate; or share it with others, thanks to Portals.
35+
36+
See it in action in our [SvelteKit+Vite demo](https://vitedemo.browserpod.io)
37+
</div>
38+
39+
<div class="m-4 flex justify-center">
40+
[Get started](/docs/getting-started) · [API
41+
Reference](/docs/reference) · [GitHub
42+
repository](https://github.com/leaningtech/browserpod-meta)
43+
</div>
44+
45+
```html
46+
<script src="https://rt.browserpod.io/20251014_102/browserpod.js"></script>
47+
```
48+
49+
## Use Cases
50+
51+
### Project showcase
52+
53+
Run a demo of your project directly in the user's browser, without any explicit setup or installation, and secured by the browser's sandbox.
54+
55+
### Interactive documentation / tutorials
56+
57+
Enrich your documentation and tutorials with interactive components, without the need for any server-side infrastructure.
58+
59+
### AI Agents environment
60+
61+
Let AI assistants and Agents run loose on your project, but isolated from the rest of your system.
62+
63+
64+
## Getting started
65+
66+
BrowserPod has a simple yet powerful [API](/docs/reference).
67+
68+
You can get up an running with few simple steps.
69+
70+
First, you need to boot your pod:
71+
72+
```js
73+
const pod = await BrowserPod.boot({ apiKey:"...", nodeVersion:"22", /*...*/});
74+
```
75+
76+
Then, you need to add your project's files to the pod. Currently, you need to fetch the contents yourself, and re-create the directory structure inside the pod's filesystem. We will add more convenient setup methods in the future:
77+
78+
```js
79+
await pod.createDirectory("/project");
80+
for await (const f of myfiles) {
81+
const response = await fetch(f.url);
82+
const buffer = await response.arrayBuffer();
83+
const fd = await pod.createFile(f.path);
84+
fd.write(buffer);
85+
fd.close();
86+
}
87+
```
88+
89+
Then, run any setup step required to initialize your project:
90+
91+
```js
92+
await pod.run("npm", ["install"], { cwd: "/project" });
93+
```
94+
95+
And finally, run the dev server (or whatever workload your project provides):
96+
97+
```js
98+
await pod.run("npm", ["run", "dev"], { cwd: "/project" });
99+
```
100+
101+
102+
Listening ports are associated with a Portal, which you can embed in the page with an IFrame, or visit from another Tab, or even another device, anywhere in the World.
103+
To get notified when a portal is created, do:
104+
105+
```js
106+
pod.onPortal(({url, port} => { /*...load iframe...*/ });
107+
```
108+
109+
## How does BrowserPod work?
110+
111+
BrowserPod is built on top of CheerpOS, an Operating System interface that provides the Linux syscall interface to Wasm programs running in the Browser.
112+
113+
BrowserPod ships with a build of Node.js that targets CheerpOS.
114+
115+
Instead of using an embedded V8 engine to run JavaScript, the Browser's engine is used instead.
116+
117+
This allows BrowserPod to run your JavaScript code at native speed.
118+
119+
Everything else (Node's builtin JS modules, libuv, and Node's internal C++ code) stays the same, to guarantee maximum compatibility.
120+
121+
Multiple versions of Node will be supported, and we plan to support new LTS versions in a timely manner.
122+
123+
Using the same foundation, we plan to support other languages and frameworks, like Python and Ruby (including Ruby on Rails).
124+
125+
## Licensing
126+
127+
BrowserPod is free for personal use and technical evaluation. See [licensing](/docs/licensing) for details.
128+
129+
## Demos
130+
131+
You can see BrowserPod in action in our [SvelteKit+Vite demo](https://vitedemo.browserpod.io)
132+
133+
## Community
134+
135+
We have a vibrant Discord community where you can ask questions, share your projects, and get community support.
136+
137+
<LinkButton
138+
type="discord"
139+
href={DISCORD_URL}
140+
iconLeft="fa-brands:discord"
141+
label="Join our Discord server"
142+
/>
143+
144+
<LinkButton
145+
type="secondary"
146+
href="https://twitter.com/leaningtech"
147+
iconLeft="fa-brands:twitter"
148+
label="Follow us on Twitter"
149+
/>
150+
151+
---
152+

‎sites/browserpod/src/content/docs/11-reference/00-BrowserPod/00-boot.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: boot
3+
description: Initialize a pod instance
4+
---
5+
6+
7+
```ts
8+
class BrowserPod {
9+
static async boot(opts: { nodeVersion?: string, apiKey: string}): Promise<BrowserPod>;
10+
}
11+
```
12+
13+
## Parameters
14+
15+
- **opts** (object) - Initialization options passed as an object
16+
17+
## Options
18+
- **nodeVersion (`string`, _optional_)** - The version of node to use. Currently only "22" is allowed.
19+
- **apiKey (`string`)** - The API key to use.
20+
21+
## Returns
22+
23+
`boot` returns a [Promise] which is resolved when the Pod is ready to be used. It returns the newly created Pod.
24+
25+
26+
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

‎sites/browserpod/src/content/docs/11-reference/00-BrowserPod/01-run.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: run
3+
description: Run a program inside the Pod
4+
---
5+
6+
7+
```ts
8+
class BrowserPod {
9+
async run(executable: string, args: Array<string>, opts?: { env?: Array<string>, cwd?: string}): Promise<Process>;
10+
}
11+
```
12+
13+
## Parameters
14+
15+
* **executable (`string`)** - The path of the program to execute
16+
- **args (`Array<string>`, _optional_)** - The command line arguments to pass to the program.
17+
- **opts (`object`, _optional_)** - Initialization options passed as an object
18+
19+
## Options
20+
- **env (`Array<string>`, _optional_)** - The environment variables to pass to the program, in the form "KEY=value".
21+
- **cwd (`string`, _optional_)** - The current working directory.
22+
23+
## Returns
24+
25+
`run` returns a [Promise] which is resolved when the command finishes running.
26+
27+
28+
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

‎sites/browserpod/src/content/docs/11-reference/00-BrowserPod/02-onPortal.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: onPortal
3+
description: Set up a callback that will be invoked when a Portal is created
4+
---
5+
6+
7+
```ts
8+
class BrowserPod {
9+
onPortal(cb: ({url: string, port: int}) => void): void;
10+
}
11+
```
12+
13+
## Parameters
14+
15+
- **cb** (`function({url: string, port: int}) => void`) - Function to invoke when a Portal is created
16+
17+
## Callback arguments
18+
- **url (`string`)** - The URL at which the Portal is accessible.
19+
- **port (`number`)** - The local port that is connected to the Portal.

0 commit comments

Comments
 (0)