bonsai.js
Advanced tools
Readme
Japanese art of growing and shaping miniature trees in containers
BonSai is a full-stack agnostic framework for the web, built upon Bun (in fact, it has Nunjucks and Sass as optional dependencies). You can install it:
bun add bonsai.js
And use it as a handler:
import BonSai from "bonsai.js";
const { fetch } = BonSai({
/*
"loaders" is the only required property, as it configures BonSai's behavior
*/
loaders,
});
Bun.serve({
fetch,
});
Powered by Bun.FileSystemRouter and some fancy tricks, BonSai takes an approach where you declare the files you want to become "routes"
loaders: {
".ext": loader
}
And all files with that file extension will be served as routes.
Lets say you have the following files:
pages
├── index.njk
├── settings.tsx
├── blog
│ ├── [slug].svelte
│ └── index.ts
└── [[...catchall]].vue
You can configure BonSai to serve those files:
BonSai({
loaders: {
".njk": nunjucksLoader,
".ts": apiLoader,
".tsx": reactLoader,
".svelte": svelteLoader,
".vue": vueLoader,
},
});
Check the
Loaderinterface
You can also specify file extensions that will be served staticly (return new Response(Bun.file(filePath))), like so:
staticFiles: [".jpg", ".css", ".aac"];
There is a caveat around
staticFiles: as all files are served using the FileSystemRouter,pages/pic.jpegwill be served as/pic
BonSai is 100% flexible, but this does not mean that it cannot be opinionated. BonSai ships with built-in (optional) loaders:
Since v0.1.0
Nunjucks is a rich powerful templating language with block inheritance, autoescaping, macros, asynchronous control, and more. Heavily inspired by jinja2.
bun add nunjucks @types/nunjucks
import getNunjucksLoader from "bonsai.js/loaders/nunjucks";
const { loader, env } =
getNunjucksLoader(/* (optional) root path and nunjucks configure options */);
// you can make changes on the nunjucks Environment object (the 'env' object).
// See https://mozilla.github.io/nunjucks/api.html#environment
BonSai({
loaders: {
".njk": loader,
},
});
<body>
{# 'server', 'route' and 'request' #}
<p>
All those objects are passed to the Nunjucks renderer to be available
globally
</p>
</body>
Since v0.1.0
Sass is the most mature, stable, and powerful professional grade CSS extension language in the world.
bun add sass @types/sass
import getSassLoader from "bonsai.js/loaders/sass";
const loader = getSassLoader(/* (optional) sass compiler options */);
BonSai({
loaders: {
".scss": loader,
},
});
Since v0.1.0
BonSai offers a simple module implementation to handle .ts, .tsx, .js and .node files:
import { ModuleLoader } from "bonsai.js/loaders";
BonSai({
loaders: {
".ts": ModuleLoader,
},
});
A server module is a regular TS/TSX/JS/NAPI (anything that Bun can import) file that have the following structure:
// optional
export const headers = {
// All reponse headers go here.
// The default Content-Type header is "text/html; charset=utf-8", but you can override it.
};
// required
export function handler(data: ModuleData) {
// data.server => Server
// data.route => MatchedRoute
// data.request => Request
// The handler must return a BodyInit or an instance of Response, whether synchronously or asynchronously.
// If Response is returned, the loader will send it and the "headers" export will be ignored.
}
Since v0.1.0
If you liked BonSai's opinion and want to enjoy all this beauty, you can use the recommended configuration:
import getRecommended from "bonsai.js/recommended";
const { loaders, staticFiles, nunjucksEnv } =
getRecommended(/* (optional) nunjucks and sass options */);
BonSai({
loaders,
staticFiles,
});
Check the
Recommendedinterface.
Since v0.2.0
You can use middlewares to override or customize the response given by the loader.
const { addMiddleware, removeMiddleware } = BonSai(/* ... */);
addMiddleware(
"name it so you can remove it later",
(response, request, server) => {
// you can stop the middleware execution chain by returning a Response
// if you want to stop the chain and override the response, return a new Response object
return new Response();
// if you want to just stop the chain, return the same Response object
return response;
}
)
.addMiddleware(/* can be chained */);
removeMiddleware(
"name it so you can remove it later"
)
.removeMiddleware(/* can be chained */);
FAQs
BonSai is a full-stack agnostic framework for the web, built upon Bun.
We found that bonsai.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.
Security News
Socket is joining forces with CISA and other industry leaders at the RSA Conference to sign the Secure by Design pledge, committing to uphold the highest security standards in our products.
Research
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.