gladejs

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)

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

mkdir MyWebSite && cd MyWebSite

npm init -y && npm i -D gladejs

2. 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"
},

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