The Bandolier (aka
- JSON APIs backends.
- Multi-page and Single-page web UIs.
- Queues for offloading processing.
- Video support with HLS, HTML, and WebTorrent Video.
- Built-in Database administration and a simple ORM.
- Authentication with passport.
- Websockets with socket.io.
- Pre-made CSS components and a simple CSS design method for non-designers.
- Unit testing and UI test automation.
- Automation commands to automate the boring tasks.
- Template generators to get started with code.
- Full but simple database administrator in the browser.
- Basic Discord integration.
- Custom documentation generation for APIs using acorn.
- Includes common things you need like lucide icons, Email DNS testing, web log analysis, in an easy to extend administrator tool.
- All implemented in reasonably sized pieces of code you can study on your own.
You can think of
bando as a belt full of simple useful web development code and practices that help you learn how to get things done. The idea is that everything in here is "similar" to features in other full stack web frameworks, but simplified so you can study them. Once you learn what's here you should be able to learn most other features in other frameworks.
This is the template project that's checked out and configured when you run the
npx bando-up command from ljsthw-bandolier. This is where the code really lives.
First, install the ljsthw-bandolier:
That will create a command you'll use to manage installs and updates of the Bandolier Template. The code for the framework lives there.
You should now be able to do this:
npx bando-up --version npx bando-up --help
If you can't then refer to the documentation for
ljsthw-bandolier, especially if you get errors regarding SSL certificates on Windows.
If you can run the
npx bando-up command then use it to create your first project:
npx bando-up create my-project
This will checkout the Bandolier Template git repository into the
my-project directory. Once it's done you can move on to Configuration.
If you checked out your first project into
my-project then do this:
cd my-project npm install
That will move you into the project directory and install all of the required software. If you get errors with
node-gyp see below on how to fix them (maybe).
npm install finishes you can configure the application:
npm run knex migrate:latest
This will setup your database, and then you can finally do the initialize command to finish the setup:
node bando.js init
This will configure some items, rerun the migrations just in case, and copy any template files that may have been missed. It will skip files you already have, and then wait for you to start the app in another window.
Open another Terminal window and start the app in
npm run DANGER_ADMIN
This starts the app in developer mode, but it's called
DANGER_ADMIN so you know for sure you should not be running it this way in production on the internet.
Once it's running, switch back to the other window and hit
ENTER. This will open your browser to
http://localhost:5001 so you can register a first user. Fill out the registration form with a fake user and hit the
Register and Continue to Payment button.
When your developer user is first registered it's not an administrator. Switch back to the window running
node bando.js init and hit
ENTER again. The command will then set the first user to
admin=1 and report
The final test is switch back to the browser and refresh the page to see that you are now administrator.
Install Error with Playwright
In theory you shouldn't need playwright to download browsers, so just tell it not to.
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
This isn't as needed on Linux as OSX, because the Playwright project forces people to upgrade their OS by claiming all versions of their project can't support any slightly older Safari versions. You also just don't need Safari, so skip the download.
Errors Related to
If this doesn't work then this might https://github.com/nodejs/node-gyp/blob/main/docs/Updating-npm-bundled-node-gyp.md which says that npm updates don't update the node-gyp it uses internally. Depending on your version you will have to run different commands, but this works for 7,8, and 9 versions:
npm explore npm/node_modules/@npmcli/run-script -g -- npm_config_global=false npm install node-gyp@latest
There's also an issue with installing node-pre-gyp where it seems you need to install @mapbox/node-pre-gyp and also node-pre-gyp.
If you're on OSX or Linux you can just run
./bando.js directly rather than
node bando.js. If you're on Windows you can use the PowerShell script
./bando instead. To make these instructions work for people who skim I'm using
This command is a simple "runner" script that looks in the directory
commands for all
.js files to provide them as commands. You can go in there right now and look at the
commands/init.js file to see what it did. The code is fairly simple, and a good one to study first. Feel free to look at the other commands as well.
NOTE: This is a very early release to have people try it and tell me how it worked on their platform. I test this OSX, Windows, and Linux but tell me if you run into installation issues, especially with regards to
The directory structure of The Bandolier is flat to avoid nested hierarchies. Nesting directories deeply makes it more difficult to work on the code, and more confusing for beginners. By flattening the structure out you have direct access to every component, and each component is clearly separated. For example, rather than try to make one directory of
.svelte files do both dynamic and static content there is a directory
client for the dynamic client "app", and
rendered for the rendered pages. This keeps thing digestible and easy to study since each directory does mostly one thing.
Here's what each directory contains:
admin- This is where the admin control panel lives.
api- The JSON api handlers live here.
bando.js- This is your main management script.
bando.ps1- This is a Windows compatible version of the script.
build.json- A build configuration used by the
commands/build.jscommand that runs esbuild.
build.prod.json- The production build configuration used in the
npm run buildcommand.
client- This is where the main web application lives, and is a dynamic Svelte front-end.
bando.jsscript runs commands out of here.
coverage- You won't see this at the start, but if you run the coverage commands then you'll see code coverage output here.
debug- Various debugging outputs end up here.
dev.sqlite3- SQLite3 is the default database (PostgreSQL coming soon).
dev.sqlite3-shm- You'll see this because the SQLite3 database is configured for performance.
dev.sqlite3-wal- Same as above.
emails- Your email templates and configurations are in here. Edit these to change how you email your users.
knexfile.cjs- This is the database configuration using knex.js.
lib- Various support utilities for are found in here, but are only for non-browser tools. Look in
client/for admin and client imports.
media- If you do videos or audio then this can be a separate directory for media. You need this so you can wipe
public/at any time.
knex.jsmigrations. You'll see all that I've made over development so you have many examples.
node_modules- Your modules when you run
package.jsonuses nodemon to trigger builds when you change something. Esbuild handles this for
npmmakes this, and you can search in here to see exact versions of your packages and what depends on what.
package.json- This configures the project. Take special node of the
"type": "module"configuration, which configures node for ES6 style ESM imports.
public- This directory should be safe to empty if you need to debug how things are being built. It is constructed from all of the other directories to create the content you would place on your webserver.
queues- This directory has queue handlers, which use Bull to offload long running processing. Email sends, Discord bot handling, Paypal notifications, Stripe notifications, and Livestream notifications are handled by these.
rendered- This is where the rendered static pages go, and you can look in
rendered/pages/blogto see an example of using this.
scripts- These are mostly scripts and "junk" other modules need, like Svelte's TypeScript configuration script, or PM2 configuration examples.
secrets- NEVER PUT THIS IN GIT. This is where your secret configuration files go. This will contain Payment keys, Discord keys, and other special configurations you don't want people to get.
socket- This contains the socket.io handlers that give easy asynchronous communication with the browser.
static- These are static files that need to be copied over to
tests- Contains the automated ava tests for the application. The majority of them use Playwright to run the browser like a user to confirm things are still working.
As you can see, this includes almost everything you'd need to learn as a full stack developer. The code included isn't 100% feature complete, but it does have the minimum features necessary to make it work. That leaves room for you to improve it and make it easier to study.
You Can Change or Remove Almost Everything
The Bandolier is designed for you to learn new technologies without having to create an entire web application from scratch. If you want to try Actix as a backend JSON server then just make it return the same JSON on the same URLs
api/ and it should work. Don't like the ORM? You could probably replace it fairly easily. Want to learn how to use React? Just start your own React app in a new directory, and slowly bring over what you need from
client/ but in React form. Don't like my CSS? All of the HTML is very simple and semantic, so you can craft almost any classless CSS you want. Converting to something like bootstrap would be some work, but you can use the
client/components as a list of things to replicate in your version. Probably the most difficult thing to replace is the is the
client/ directory, since
rendered/ use components, but if you really want to learn a front-end framework then replicating all of the components in
client/components would be an incredible way to learn.
The reason this works is because the code in
api/ doesn't really depend on anything in
admin/. If it uses something in
queue/ it's through a library so you can replace it easily, or possibly even just use the Bull from your favorite backend language. Bull just uses redis, and you could just replace all of that. There's also a large test suite in
tests/ that you can keep running to make sure your changes are working.
Finally, all of the code is reasonably sized. Most files are about 100 - 500 lines of code with not too much convolution or deep references. You could probably pick a random file and spend a few hours to study it. Many of the source files also teach a different technique. For example, the
client/fsm.js file implements a simple Finite State Machine, which is used to make HLS video work in
client/components/HLSVideo.svelte. Then in
client/components/WTVideo.svelte there's more traditional callback style for handling WebTorrent videos so you can learn both techniques.
Since all of this code is right there, and there's lots of tests, you can feel free to experiment while you study it. When you want to use it for something real, you can use what's there, and improve what you need for your application.
Built-in Development Tools
The Bandolier tries to use the web browser to make web development easier. When you first go to 127.0.0.1:5001 you'll see a mostly blank page with a bunch of icon in the top header. Click on the keyboard. Now you're in the built-in administrator that provides:
- Simple database administration that understands the SQLite3 schema. It's good enough to manage your application for quite a while.
- Quick Email testing tools to make sure your DNS entries are probably correct.
- Quick email sending test tool to test your email configuration.
- Viewing anonymized web server statistics generated by the
- Full Icon browser/finder for the included lucide icon set. This is probably all of the icons you'll ever need, and there's code you can use to package up your own set of
.svgicons if you want.
- Component browser for all of the components in
client/components, with demos, quick docs, and demo code.
- Browser for all of your
socket/routes so you can see what's configured and look at the code.
- The "Djenterator", which is a visual code template generation. It has a simple JSON file you edit to change the code and then you copy it out to get started.
You can also type
ctlr-alt-b and a little "hotbar" will pop-up with quick links to common things you need quickly like errors, icons, routes, etc. This makes development faster as you can access tools directly from the pages you're working on.
Making Your First Changes
The documentation is light right now, but try this:
- Open the
client/pages/Home.sveltefile in your editor.
- Change the
Welcome!text to say what you want.
- Type ctrl-alt-b and click on the Icons tool.
- Find an interesting icon, and click on its block. The code for that icon is now copied.
- Go back to
Home.svelteand paste that Icon somewhere.
- Save and it should reload (hopefully), if not refresh.
- Break this page by removing some important character.
- It should refresh and display an error pop-up.
- Click on the error pop-up and it will open the browser to an error view.
- Fix the error, it should reload and the error should go away, but sometimes you have to refresh (bug).
- Look at
client/routes.jsto see where pages are configured for each URL.
ctrl-alt-band go to Library. This is the library of component demos for everything in
client/components. Browse around and try them out in the
- Look at the code in
api/register.jsto see a good example of a JSON API.
- Look at
lib/ormish.jsfor the simple ORM(ish) built on top of knexjs. There's some fancy tricks in there too.
- Look at
lib/models.jsfor examples of using ORMish.
- Click on the "keyboard" icon in the header (must be admin) to view other admin features, especially the
Tablesadmin for the database.
- Then continue studying anything you find interesting and trying to change the existing pages.
This should give you a quick crash course in how the framework operates while I work on better documentation and instructions.
This is a first rough ALPHA release to get the project published and get some victi
^H^H^H^H^H...users testing it and telling me how it works so far. You aren't expected to be able to figure it out since I haven't completely documented it, but you should feel free to explore the code, study what's there, and see what you can do. The next release will have reference documentation and more code cleaning, then after that videos demonstrating the important features and showing how to use the tools included.
bando to create their own projects, and also learn how to implement the important elements on this stack. Once the course is done I'll start writing more public documentation for the framework as well as more demonstrations of using it to implement common websites.