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.