In this final section of Building Apps, we'll talk about optimizing via building, and integrating by launching to web hosts, servers, especially those with automatic building features so it frees up our workflow it will build without us having to think about it. In other words, let's make our code go fast and our workflow go smooth!
Why build? Let's start with a "thought experiment", where we fast forward into the future. Imagine that as you create more and more components, you begin splitting them up into more component libraries. Also, as mentioned previously, perhaps you find some nice component libraries that others have made that you want to use in your project. In the end, you might find yourself with dozens of HTML files being loaded, scattered in different directories.
In this situation you will have too many
<Library>tags, meaning your page may take a long time to start-up. As it's downloading all the different files, the browser will be showing the ugly, unformatted text in the mean-time. On slow connections, this could be end up being a frustrating experience for users. This is why building to one file is useful.
Building: Packing it all up
"Building" is a feature of Modulo where it packs up all the components,
.css files, respectively. This single file file, called a build, contains
all the code from all your components (including CParts that were split off
These "builds" are fully independent: Once the "build" file is included using a
<script src="...">, all your components on that page will work, without any
need for including Modulo or your libraries specifically. In other words, this
tag replaces all the boilerplate you have on your page, and you can remove all
the importing-type code (e.g.
<script Modulo>) from your HTML files,
replacing it only with the single script tag. Not only that, it will also
sizes. This causes the components to load much faster.
Generally, developers create builds before "launching" their site to "production" (e.g. publishing their site for the world to see), since it results in the fastest possible loading time. Note that you should only attempt to edit your original, source files: Builds are only for releasing or publishing, but not for editing. Never directly edit builds; instead, create new ones.
Pre-rendering HTML for instant loading
To build a project, we will need to use the Modulo Command Menu. The
console is a feature of all web browsers. As a web developer you likely have
used it: It's a panel, hidden by default, where JS, CSS, and other such error
messages are displayed. While most JS frameworks require NPM-based tools to
build, Modulo can be built right from your browser's console, simply clicking
build commands in the
COMMAND menu, that is visible in your browser
developer tools console.
Build files will look like:
modulo-build-x9f2za71.css. Note the so-called "hash" (e.g. “xx4bz9v4”): These
unique IDs identify each JS and CSS file that is generated by Modulo. If you
change something in your components, you will cause one (or both) of these
hashes to change, if they end up affecting the component's behavior (
it's appearance (
Try it now
Open up your HTML file in your browser (e.g. Firefox or Chrome/Chromium). Do not open your component library HTML files: Be sure to open the file that is doing the importing and using the components, not the file(s) that contain the component definitions themselves.
Bring up the console: Press
Control+Shift+J(Linux, Windows) or
Command+Option+J(macOS) on your keyboard to open the Console. Alternatively, you can right-click with your mouse and select "Inspect", and then go to the Console tab.
Optional: Within the newly opened developer tools, navigate for a moment to the "Network" tab. Force refresh your browser. You should see a list of "requests" being sent, including one for each component library that needs loading. For example, if we named our component library "./static/my-component-lib.html", we'll see an additional request for this HTML file. If we had further split our files using "-src=", we'll see even more requests.
Do you see a Modulo logo (
%), with the word
COMMANDS? Click on
COMMANDS, and possibly one more time (on Firefox), and you should see a command menu, containing commands like
test. To build, simply click the "
Note: Look in the upper-right hand of your browser. You might see a warning, prompting you about "Allowing multiple downloads". You should allow it, otherwise it will block the generated files from being downloaded. If you see no warnings about this, then just continue to the next step.
The HTML "build" is a copy of the HTML page you were working on, with two important differences:
Difference #1: It's been modified to include the built versions of the CSS and JS: A link tag to include the CSS file is inserted before the
</head>, and a script tag inserted before the
</body>tag to include the JS file.
Now, open up your "build" file. If all went well, it should look and behave exactly as before, except load much faster.
Tip: If all went well after building, you should see a link to the command you just ran. Clicking on the link will refresh the page, causing it to build again. You can also just hit refresh (Ctrl+R or Command+R) to rebuild. Consider keeping this window open, or as another tab, and resuming work in another window. Then, to rebuild, simply switch back to this window, and either click the button or hit refresh!
Important: Don't edit your builds! Built files are disposable. Don't edit the HTML, JS, or CSS files produced. Instead, continue working on your original "source" files, and then build again. The purpose of these new "built" files is to only share them when you are done with your website. These should only be used when "launching" your site. Your development should continue on the "source" files.
This can easily trip up beginners: The build "freezes" the component library in
time, and you'll have to run build again if you change anything. A common
mistake is forgetting that you are editing the original
.html file while
using the built
.js version, causing much confusion as to why your changes
don't take effect!
Servers & integration
This section contains advice on launching Modulo as a static site generator on various website hosting companies and platforms. It also discusses integrating Modulo.js as purely a component library supplier with other frameworks. This might include backend frameworks or other frontend frameworks.
It also talks about workflows. In this case, different workflows for component designers and developers to work in a steady rhythm to maintain component libraries that are then used elsewhere, e.g. in a backend app, or a static app.
Which one to choose?
Modulo-centered stack - Modulo is the main framework you are using to build a static site and/or single page app, potentially with API integration, and/or "serverless" functions (covered first)
Launching Modulo as a SSG with autobuilding
When to use it - When you are building a Modulo-focused app, and automatic building and integration of Modulo in the site is so important. It's also important to be able to update frequently, as quickly as you can upload your changes with
Using the NPM package
modulocli, you can automate building Modulo. This is
the same Puppeteer based script that this website uses to build itself. It will
loop through all items in input directory running the in-browser
command on each, and saving the output to the
Autobuilding on Netlify
Netlify is a company that provides free and paid web hosting plans for "Jamstack" and similar SSG-style projects.
If you started with the SSG / Jamstack template, your project should be ready
to launch to Netlify already. Just upload or use git! Make sure everything gets
pushed in the exact structure it came in, making sure the
intact at the top level (if curious, see see below).
Netlify should server-side build everything.
Autobuilding on GitHub
Git - Git is essential when automating workflows. If you are brand new, you might want to start using git using a GUI. One popular free GUI for Git is GitKraken, for macOS, Linux, and Windows. You can follow a tutorial about how to use GitKraken here
GitHub is a git hosting company owned by Microsoft that provides free and paid hosting plans for public and open source projects.
If you started with the SSG / Jamstack template, your project should be ready to launch to GitHub after completing the following steps:
modulo.ymlfile from here:
Ensure it is put in the exact same directory structure:
- Make a hidden directory structure like:
.github/workflowsin your repository
- Add the
- Make a hidden directory structure like:
Ensure necessary features are enabled
- Ensure GitHub Workflows is enabled on your repository
- Ensure GitHub Pages is enabled on your repository
Verify the site is getting launched after each push
Troubleshooting GitHub Pages
- Verify by visiting:
- If done correctly, every push to that repository will trigger an auto-build, launching your sit at the domain
- Troubleshooting: Just getting 404? Make sure your URL looks something like
(for tuxpenguin's repo "new-modulo-app"):
- Troubleshooting: Still getting 404? Try possibly adding an HTML path if you
don't have an index.html, so the URL will end up looking like:
- Troubleshooting: Still not seeing changes? Try doing "hard refresh", and also waiting a few minutes, GitHub pages can end up getting cached and not reflecting changes. If GitHub servers are busy, and you are on a free plan, you could end up waiting even longer for it to re-build and re-launch.
Custom: Using a package.json
If one of these instructions doesn't work, or your host isn't listed here, you
may need to customize the
package.json file further.
Many hosts, including Heroku and Netlify, expect a Node.js
For Modulo.js to automatically build on these servers, we can use a
script as part of the
mdu.js package to build the site using the same script
that the official site does.
Examine the following one, which is slightly modified from the one that comes with the template:
You can use this
package.json for your own Modulo projects. This will enable
it to be automatically server-side built every time you upload it to the
server. This can be very convenient, and result in a much better experience for
users than the development version.
- The setting you will mostly likely need to edit are the
"output": "build"setting (
buildis a common default, but others might expect
docs/(GitHub pages) or
- You might want to change
inputto be a different value as well. This should be where you put all your HTML and other web files (e.g. your "src" or "source" files). This is your "www" or your root directory that will be hosting all your website, e.g. the
index.htmlhere should be the one for your top-level domain (that is, in this example,
Integrating as a library
You might wonder how to integrate this process with pre-existing web apps, or apply it in a real-life web development team, as we've thus far only been talking about developing Modulo components in isolation.
This is where workflow comes into play, i.e. the patterns and procedures you follow to keep a project humming along. When you use Modulo, or any framework, enough, the question arises of workflow, or good patterns of use that facilitate contiued development and deployment of a product in a team setting. In this section, we'll look over possible approaches to integrating a Modulo.js-powered component library with some other framework, such as a backend framework.
Manual workflow: Without automated builds
When to use it - The showcase.html workflow is great if Modulo is only going to contribute a few components that you don't update that often after periods of focused development. For example, maybe you are tasked with enhancing a form interaction, or integrating a specific JSON file or API so to add a splash of live data on an otherwise static portion of the site. In these cases, it's workable to keep your "showcase" development in as separate location, then manually build and integrate whenever you make changes, essentially like you are developing your own internal library that you occasionally "release".
One useful workflow for integrating Modulo with existing projects is to have a sort of sandbox "testing page" or hidden internal-only "showcase" HTML page (i.e. similar to a "story book" or "design guide" of components). On this page, you develop and showcase your re-usable components, both to ease development, and also to serve as a demonstration for other members of your development team or organization.
From this "showcase" page, you can then run
build to generate built JS files
and CSS files whenever you have completed sufficient work on your components
that you want to integrate and release into the rest of the project. The
"self-packing" nature of these builds make the integration no harder than
adding any other script or link tag. This works especially well for small
projects, and avoids the need for a complicated automated build process for
component libraries that you might only occasionally change. One downside of
this workflow is that you might not be able to pre-render any of the pages you
are integrating with, so there might be slight delays in mounting your
Try it Now
Try out the "Showcase Workflow" for creating and maintaining a library of built components that you integrate into another website, such as a backend MVC app.
Create a new "showcase" page that imports your component library.
- You can put it in
/showcase.htmlto make it easy to find.
- You can even put it in your
/static/directory to keep it a bit more "hidden", e.g.
- You can put it in
In your showcase file, import your Modulo header like any other file.
Then, to "use" this workflow, work on developing an assortment of components in isolation on this file.
When you are ready to integrate it with the other app, export the JS and CSS file, and add script tags to your template of your other app.
Then, in the other app, be sure to include the necessary tags:
- Now, Modulo components can be used to "spice up" your otherwise simple HTML templated app!
Example: Integration with a "legacy" PHP project
Automated workflow: Integrating automated builds
Automatically integrating Modulo into a backend app is beyond this tutorial.
Instead, you should examine the documentation of the other framework, and let
it "drive". For example, see if you can find instructions for integrating
React in general -- those might work for Modulo as well,
since it uses
npm run build for the same purpose, and outputs to the same
Part 3: Summary
In this tutorial, we started with trying Modulo's self-building feature, and then went on to discuss ways to automate it or structure workflow around it.
- build - Combining all your JS and CSS together into a single file that loads faster, and pre-render the HTML so there's no flicker.
- hash - These unique IDs identify each JS and CSS file that is generated by Modulo.
- automated build - Setting it up so it builds automatically whenever you make a change
That's all for the Building Apps with Modulo tutorial!
Continue perusing the full Modulo Documentation to focus learning on a particular topic