gladejs: A JavaScript repository from tigt

Helping Marko to Roll Uphill, Pass the CaScadeS and reach the GladeJS at 11' for Tea.

Description

GladeJS is a simple Rollup setup for bundling Web Sites built with Marko and Eleventy.

If the above description does not speak to you, try one of these for size :

This is a Jamstack dual SSG / SSR frontend framework using Rollup
It transforms your "pages" into a modern web "_site" ready for Prod
It is the best bundler (you're not using) combined with the simplest
SSG (you want to use) and the fastest UI lib (you've never heard of)
In the end, it is nothing more than a well documented Rollup config

Or maybe listing what it's not and doesn't do will give you a better idea :

This is not yet another framework to learn (the CLI is Rollup's, the configuration is Eleventy's)
The tools are not hidden, you interact directly with Eleventy, PostCSS, Terser, Babel, CSSnano,...
It does not force any JS in the output (unless you use Marko's client-side components, of course)
You will not find any mention of SPA, routes, servers, nor any GladeJS special API or <Link> tag

This project requires NodeJS v14.x or superior and the included "npm" CLI v6.14 or superior.
It is tested on the latest versions of NodeJS v14, v15 & v16 on MacOS, Ubuntu and Windows.

Installation

The complete installation instructions are in this section, don't look for any more details, it's all here.

Automatic (not ready yet)

A "@gladejs/create" automatic initialization package is planned for the v1.0 release.
It will allow for a simple "npm init @gladejs MyWebSite" installation, but not yet.

Manual (in 3 easy steps)

Create a new NodeJS project & install GladeJS as a "devDependency" :

mkdir MyWebSite && cd MyWebSite

npm init -y && npm i -D gladejs

Replace the "scripts" section in your new "package.json" file with :

"scripts": {
    "vite": "rollup -c --watch --environment VITE_ENV",
    "live": "rollup -c --watch",
    "build": "rollup -c",
    "clean": "rimraf build _site",
    "build:prod": "rollup -c --environment NODE_ENV:production"
},

Copy the GladeJS Rollup configuration file into your project folder :

npx shx cp node_modules/gladejs/rollup.config.mjs .

Documentation [WIP]

The bare minimum to get you started is here, but you'll find detailed information in the "docs" folder.

Rollup Configuration

A single "rollup.config.mjs" file is used to configure your build process.
If you are not a NodeJS and/or Rollup guru, fret not, the defaults are just fine.
Nevertheless, give it a quick glance, it's relatively organised and documented.

NPM Command Scripts

GladeJS is directly controlled via NPM scripts, using the following commands :

"npm run vite" to run ViteJS "watch mode" for fast development
"npm run live" to run Rollup "watch mode" for live development
"npm run build" to bundle your project without any minification
"npm run clean" to delete all files & folders created by GladeJS
"npm run build:prod" to bundle your project with minification

Pages & Components

The files & folders structure is marked by a distinctive lack of imagination :

Web Pages go into the "pages" input dir and Marko UI Components into the "components" dir.
There is "layouts" for 11ty Layouts, "includes" for Includes and "datastores" for Data Files.
CSS Styles are picked up from any "style.{css|less|sass|scss|styl}" file placed next to any
"index.{html|md|marko|11ty.js|liquid|njk|hbs|mustache|ejs|haml|pug|jstl}" page.

Assets & Resources

Static assets are pulled in using relative, absolute or NPM package file paths :

Using the standard ESM "import" keyword at the top of any page for CSS, JS and images.
Using the "src" attribute or any normal HTML resource tag ("script", "style", "link").

CSS & JS resources are "swallowed" by Rollup to be bundled, chunked and pressed.

Don't forget to inject them back into the HTML HEAD tag using "<gladejs-rollup />".
Use the name, type, scoped & rollup="ignore|bundle" attributes for more control.

Now, enter the GladeJS "docs", follow the floating possum around 11ty or RTFMD (Read The Fabulous Marko Docs).

Contributing [WIP]

While still in early development, everything is in place to receive your contributions.

Get acquainted with the project PHILOSOPHY and general direction
Consult the ROADMAP to see where things stand and what's the master plan
Look for low hanging fruits in the "Open Issues Status" project board
Read the CONTRIBUTING guidelines carefully, they are short and to the point

You are now ready to contribute, so ... where is the code ? Mostly in another castle, Mario.

The core engine is here, but it is more configuration than source code
The integration tests are here, but they are more documentation than test
The documentation dir is here and contains the actual meat of this project
The "@gladejs/eleventy" package integrates 11ty into Rollup for GladeJS
The "@gladejs/rollup" package contains all of the necessary glue code

Finally, GladeJS relies on over 22 major OSS projects, including 7 Rollup plugins,
contributing to any of them, not only benefits this project, but also many others.

tigt/gladejs