Getting Started

If you're new to the Waibu Web Framework, we recommend you to read and follow along with Bajo Tutorial and Dobo Tutorial first, as this document is the continuation of them

Bajo also has a sub-framework for serving the web called Waibu.

Fastify and its ecosystem have been chosen as the web engine. Fastify is known to be one of the fastest, most solid, and robust web frameworks available for Node.js. Waibu wraps Fastify and its plugins to work like the Bajo plugin system and introduces several methods to make working with Fastify easier and more enjoyable.

To install Waibu and its dependencies, do this:

$ npm install waibu bajo-extra

and add waibu and bajo-extra to data/config/.plugins file.

By default, Waibu listens on host 127.0.0.1 and port 7771, so you can open your favorite browser and point it to the URL http://localhost:7771.

A web framework is a very broad topic on its own. To make it more manageable, Waibu introduces the concept of a web app: a normal Bajo plugin that extends Waibu by providing a very specific task.

Static Resources

The first web app to note is the one that serves static resources, waibu-static. Installation is very straightforward:

$ npm install waibu-static

and again, don't forget to add waibu-static to data/config/.plugins file.

Static Assets

This plugin serves static assets:

With the route path /asset/{ns-prefix}/*.
Static assets are served from the {plugin-dir}/extend/waibuStatic/asset directory.
Where {ns-prefix} is a prefix string defined by its corresponding plugin. If this prefix is missing, it defaults to the plugin's alias.
And {plugin-dir} is the plugin's base directory.

Now, create the main/extend/waibuStatic/asset directory and add some static assets to it. For example, let's create main/extend/waibuStatic/asset/hello.txt and add some text in it.

When you restart your app, your screen should show you a bunch of logs like these:

$ node index.js --log-level=trace
...
2025-09-19T01:09:42.338Z +11ms INFO: waibu Server is ready
2025-09-19T01:09:42.346Z +8ms TRACE: waibu Loaded routes
2025-09-19T01:09:42.346Z +0ms TRACE: waibu - /asset* (OPTIONS)
2025-09-19T01:09:42.347Z +1ms TRACE: waibu - /asset/main/* (HEAD|GET)
2025-09-19T01:09:42.347Z +0ms TRACE: waibu - /asset/static/* (HEAD|GET)
2025-09-19T01:09:42.348Z +1ms TRACE: waibu - /asset/~/bajo/dayjs/* (HEAD|GET)
...

If you visit http://localhost:7771/asset/main/hello.txt, you'll get the same exact content you just added.

Virtual Assets

In the app logs above, you might be wondering what route paths starting with /asset/~/{ns} are all about. In waibu-static terms, it's called virtual assets. It's a way to export any directory within a plugin to be served as static assets.

Imagine you're writing a plugin that needs a specific package called hybrid-pkg from npm, and your frontend needs the exact same package. Without virtual assets, you would have to copy the exported files or directory to your plugin's asset directory. With virtual assets, you only need to do the following:

Create {your-plugin-ns}/extend/waibuStatic/virtual.json
Enter the following items into the file:
```
[{
  "prefix": "hybrid-pkg",
  "root": "node_modules/hybrid-pkg/dist"
}]
```
The above statement instructs virtual assets to create the route path /asset/~/{your-plugin-prefix}/hybrid-pkg/* that is mapped to {your-plugin-dir}/node_modules/hybrid-pkg/dist
Restart your app

Now you can use the same resource for frontend. Your request will be in the form of http://localhost:7771/asset/~/{your-plugin-prefix}/hybrid-pkg/file.js