{"id":13469395,"url":"https://github.com/losfair/blueboat","last_synced_at":"2025-05-15T04:05:56.328Z","repository":{"id":36984978,"uuid":"325985449","full_name":"losfair/blueboat","owner":"losfair","description":"All-in-one, multi-tenant serverless JavaScript runtime.","archived":false,"fork":false,"pushed_at":"2023-02-23T01:32:48.000Z","size":1394,"stargazers_count":1925,"open_issues_count":31,"forks_count":57,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-13T19:04:45.929Z","etag":null,"topics":["javascript","runtime","rust","typescript"],"latest_commit_sha":null,"homepage":"https://blueboat.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/losfair.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-01-01T13:35:07.000Z","updated_at":"2025-04-25T11:01:38.000Z","dependencies_parsed_at":"2024-01-17T16:06:56.440Z","dependency_job_id":"2bb87f0e-3a77-4636-9e24-b709db9d47ba","html_url":"https://github.com/losfair/blueboat","commit_stats":{"total_commits":479,"total_committers":2,"mean_commits":239.5,"dds":"0.029227557411273475","last_synced_commit":"7b451f709049620715d54543e6f9cc9280f87c72"},"previous_names":["losfair/rusty-workers"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/losfair%2Fblueboat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/losfair%2Fblueboat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/losfair%2Fblueboat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/losfair%2Fblueboat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/losfair","download_url":"https://codeload.github.com/losfair/blueboat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270646,"owners_count":22042859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","runtime","rust","typescript"],"created_at":"2024-07-31T15:01:37.436Z","updated_at":"2025-05-15T04:05:51.316Z","avatar_url":"https://github.com/losfair.png","language":"Rust","readme":"# Blueboat\n\n![CI](https://github.com/losfair/blueboat/actions/workflows/ci.yml/badge.svg)\n\nBlueboat is an all-in-one, multi-tenant serverless JavaScript runtime. See [the site](https://blueboat.io/) for a brief introduction on features.\n\nA simple Blueboat application looks like:\n\n```ts\nRouter.get(\"/\", req =\u003e new Response(\"hello world\"));\n\nRouter.get(\"/example\", req =\u003e {\n  return fetch(\"https://example.com\");\n});\n\nRouter.get(\"/yaml\", req =\u003e {\n  const res = TextUtil.Yaml.stringify({\n    hello: \"world\",\n  });\n  return new Response(res);\n});\n```\n\n- [Blueboat](#blueboat)\n  - [Quickstart (single-tenant mode)](#quickstart-single-tenant-mode)\n  - [The JavaScript API](#the-javascript-api)\n    - [Web API compatibility](#web-api-compatibility)\n    - [No local resources](#no-local-resources)\n  - [Developing on Blueboat](#developing-on-blueboat)\n    - [TypeScript type definitions](#typescript-type-definitions)\n    - [API documentation](#api-documentation)\n  - [Deploying Blueboat](#deploying-blueboat)\n    - [Single-tenant](#single-tenant)\n    - [Multi-tenant](#multi-tenant)\n  - [Frameworks](#frameworks)\n    - [Flareact](#flareact)\n  - [Contributing](#contributing)\n    - [Build locally](#build-locally)\n    - [Build process internals](#build-process-internals)\n  - [License](#license)\n\n## Quickstart (single-tenant mode)\n\nThis pulls, builds, and runs the [hello-world](https://github.com/losfair/blueboat-examples/tree/main/hello-world) example.\n\nPrerequisites: [cargo](https://github.com/rust-lang/cargo), npm, git, docker\n\n```bash\ncargo install boatctl\ngit clone https://github.com/losfair/blueboat-examples\ncd blueboat-examples/hello-world\nnpm i \u0026\u0026 boat pack -o build.json\ndocker run --rm -d -p 127.0.0.1:3001:3001 \\\n  -v \"$PWD:/app\" \\\n  --entrypoint /usr/bin/blueboat_server \\\n  -e RUST_LOG=info \\\n  -e SMRAPP_BLUEBOAT_DISABLE_SECCOMP=1 \\\n  ghcr.io/losfair/blueboat:v0.3.1-alpha.5 \\\n  -l \"0.0.0.0:3001\" \\\n  --single-tenant \"/app/build.json\"\ncurl http://localhost:3001 # \"hello world\"\n```\n\n## The JavaScript API\n\n### Web API compatibility\n\nBlueboat prefers to keep compatibility with the Web API when doing so is reasonable.\n\n* Things like `fetch`, `Request`, `Response` and `URL` are built-in.\n\n### No local resources\n\nBlueboat is a “distributed-system-native” runtime and prioritizes frictionless scalability over single-node performance. Local resources are abstracted out and replaced with their equivalents in a distributed system:\n\n* Files → Key-value store\n* Sockets → Event stream\n* Single-file databases → Key-value store, `App.mysql` and `App.postgresql` object families\n* FFI → WebAssembly\n\n**Read and write files**\n\n```ts\n// Don't: The filesystem is a local resource\nimport { writeFileSync } from \"fs\"\nwriteFileSync(\"hello.txt\", \"Hello from Node\")\n\n// Do: Use the key-value store\nconst ns = new KV.Namespace(\"files\")\nawait ns.set(\"hello.txt\", \"Hello from Blueboat\")\n```\n\n**Stream data to client**\n\n```ts\n// Don't: Sockets are a local resource\nimport { WebSocketServer } from \"ws\";\nconst wss = new WebSocketServer({ port: 8080 });\nwss.on(\"connection\", (ws) =\u003e {\n  ws.on(\"message\", (data) =\u003e {\n    console.log(\"received: %s\", data);\n  });\n  ws.send(\"something\");\n});\n\n// Do: Use the PubSub API\nRouter.post(\"/send_to_group\", async req =\u003e {\n  const { groupId, message } = await req.json();\n  await App.pubsub.myChannel.publish(groupId, message)\n  return new Response(\"ok\");\n});\n```\n\n**Use SQL databases**\n\n```ts\n// Don't: SQLite databases are stored on the local filesystem\nimport { DB } from \"https://deno.land/x/sqlite/mod.ts\";\nconst db = new DB(\"test.db\");\nconst people = db.query(\"SELECT name FROM people\");\n\n// Do: Use `App.mysql` or `App.postgresql`\nconst people = App.mysql.myDatabase.exec(\"SELECT name FROM people\", {}, \"s\");\n```\n\n## Developing on Blueboat\n\nYou can use your favorite JS/TS bundler to build your project for Blueboat. [webpack](https://github.com/webpack/webpack) works, and other bundlers like [esbuild](https://github.com/evanw/esbuild) and [bun](https://github.com/oven-sh/bun) should work too.\n\nYou can package and run your apps with single-tenant mode as described in the [Quickstart](#quickstart-single-tenant-mode) section, or deploy it on a multi-tenant service like [MagicBoat](https://magic.blueboat.io).\n\n### TypeScript type definitions\n\nPull in the [blueboat-types](https://www.npmjs.com/package/blueboat-types) package in your TypeScript project, and add it to your `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\n      \"blueboat-types\"\n    ]\n  }\n}\n```\n\n### API documentation\n\nWhile there isn't a lot of documentation on Blueboat's API yet, the global object declared in [jsland](https://github.com/losfair/blueboat/tree/main/jsland) can be seen as the source-of-truth of the public API.\n\nMeanwhile, refer to [the tracking issue](https://github.com/losfair/blueboat/issues/65) for a high-level overview of the API.\n\n## Deploying Blueboat\n\nThere are two options for deploying Blueboat apps.\n\n### Single-tenant\n\nThis mode works well for local development and private self-hosting. The steps are described in [quickstart](#quickstart-single-tenant-mode).\n\n### Multi-tenant\n\nThis is a fully optimized mode for multi-tenant operation. [See the guide](https://bluelogic.notion.site/Multi-tenant-Blueboat-deployment-f25c522955c04e59b5771954f8702c14) to deploy a multi-tenant environment yourself, or request access to our hosted environment, [MagicBoat](https://magic.blueboat.io).\n\n## Frameworks\n\nSimple web backends with JSON API and template-based rendering can be built without requiring any third-party frameworks. If you have more complex needs like server-side rendering React or just prefer a different style of router API, third-party frameworks are also available.\n\n### Flareact\n\n[Flareact](https://flareact.com/) is an edge-rendered React framework built for Cloudflare Workers. Since Blueboat and Workers both implement a large (and mostly overlapping) subset of the Web API, Flareact also works on Blueboat with some modifications in the entry script.\n\nSee the source code of [my blog](https://github.com/losfair/blog) as an example of using Flareact with Blueboat.\n\n## Contributing\n\n### Build locally\n\nClone the repository, and run `./build.sh`.\n\n### Build process internals\n\nNormally the build process is handled automatically by `build.sh`. Here are some internals, in case you need it.\n\nBlueboat is built in three stages: *jsland build*, *rust prebuild* and *rust final build*. The *jsland build* stage bundles `/jsland/`; the *rust prebuild* stage generates a `blueboat_mkimage` binary that is used to generate `JSLAND_SNAPSHOT` from `/jsland/`; and the *rust final build* stage generates the final `blueboat_server` binary.\n\nPlease refer to [the CI script](https://github.com/losfair/blueboat/blob/main/.github/workflows/ci.yml) for a reproducible set of steps.\n\n## License\n\nApache-2.0\n","funding_links":[],"categories":["Rust","javascript","Miscellaneous"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flosfair%2Fblueboat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flosfair%2Fblueboat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flosfair%2Fblueboat/lists"}