This is the template project that's checked out and configured when you run the bando-up command from ljsthw-bandolier. This is where the code really lives.

17 KiB

Raw Permalink Blame History

Introduction

The Bandolier (aka bando) is an educational web framework featured in the Learn JavaScript the Hard Way course. The Bandolier contains all of the features a full stack developer would need to learn, but with smaller easier to understand implementations that are fully visible in the project. It includes implementations of:

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.
Helpful video processing in JavaScript.
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.

About `bandolier-template`

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.

Installation

First, install the ljsthw-bandolier:

npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git

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.

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).

Once 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 DANGER_ADMIN mode:

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 FINISHED!.

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 `node-gyp`

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.

The `bando.js` Script

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 node bando.js.

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.

Quick Tour

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 node-gyp.

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.js command that runs esbuild.
build.prod.json - The production build configuration used in the npm run build command.
client - This is where the main web application lives, and is a dynamic Svelte front-end.
commands - The bando.js script 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.
migrations - The knex.js migrations. You'll see all that I've made over development so you have many examples.
node_modules - Your modules when you run npm install.
nodemon.json - The package.json uses nodemon to trigger builds when you change something. Esbuild handles this for admin and client code though.
package-lock.json - npm makes 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/blog to 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 public/. It's things like icons, images, browser JavaScript code, etc.
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 admin/ and 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 client/ or 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 bando.js loganalyzer command.
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 .svg icons 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 api/ and 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.svelte file 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.svelte and 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.js to see where pages are configured for each URL.
ctrl-alt-b and go to Library. This is the library of component demos for everything in client/components. Browse around and try them out in the client/pages/Home.svelte.
Look at the code in api/register.js to see a good example of a JSON API.
Look at lib/ormish.js for the simple ORM(ish) built on top of knexjs. There's some fancy tricks in there too.
Look at lib/models.js for examples of using ORMish.
Click on the "keyboard" icon in the header (must be admin) to view other admin features, especially the Tables admin 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.

Current Status

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.

After that, further development will be focused on supporting the Learn JavaScript the Hard Way course where students will use 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.

17 KiB Raw Permalink Blame History