Skip to content
Incrementally build statically-linked pages and servers with tup.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
init
.gitignore ▒♥︎░ Jun 3, 2019
LICENSE ▒♥︎░ Jun 3, 2019
README.md Updated browserslist usage; version bump. Jun 5, 2019
imu.js
package-lock.json ▒♥︎░ Jun 3, 2019
package.json

README.md

imu 🔥 🐷 🔥

Incrementally build statically-linked pages and servers with tup.

What is it? Why?

This is an opinionated build system that has made all the decisions for you.

It works with simple commands. It is incremental and runs only tasks when needed. Eligible tasks are run in parallel. It also prevents stale files from leaking into your deployment directory. You do not need to specify your project dependencies for this to work, but in exchange you need to follow the provided project layout.

It uses tup to accomplish this.

For rapid prototyping, Stage0, S.js and TailwindCSS related libraries are provided. Their use are optional and they consume roughly 3~6KB of the compressed bundle size when optimized.

JavaScript is ES6, CSS is PostCSS Preset Env, HTML is preprocessed, all is aggressively minified and packed into single HTML page. It is easy to build many pages, with as little or as much CSS and JavaScript as needed -- the natural unit for splitting up bundle sizes.

At around 64KB~128KB compressed, you may want to start thinking about a new page.

Reading the .imu source installed into your project is a good idea. You are encouraged to fork, modify and otherwise twist the contents to your needs.

Requirements

Optional Dependencies

Neither tup nor imu-build are required to build an imu project. Your end-users may always execute npm build in the project root to get a release build.

Tup

By default, it generates tup build logic to provide the incrementing, parallel build and deployment system.

Although it was designed to work with tup, its use is optional. If it is not found, the entire project is built as a single synchronous thread. This is both slower, not incremental and may also result in stale artifacts in the deployment directory, but this will allow anyone to build a project with no additional dependencies beyond node.js.

imu-build

This guide will assume you will have installed imu-build in order to use the imu command from anywhere in the project tree. However, from the project root you may always use npm run to execute the very same commands.

There is no default command for npm run by itself, however npm run build will execute a release build.

You will also need to run the new command as npm run new -- -p example with the -- in order to pass arguments.

The init command is only available with imu-build.

Client Overview

Commands Description
imu init Installs the build scripts and npm dependencies.
imu new [options] Create new projects and templates.
imu client-debug Builds the client in debug mode.
imu client-release Builds the client in release mode.
$ npm install --global imu-build
$ mkdir (Project)
$ cd (Project)
$ imu init
$ imu new --page (PageName)
$ imu

This will build an empty page to confirm the toolchain is working. You may edit the code in client/pages/(PageName) to further experiment.

After making changes, executing imu inside the project directory will rebuild only the necessary files. For speed, this is an unoptimized build. Running imu client-release will compile an optimized, ready-to-deploy build.

When you are ready to start a new component for your page:

imu new --page (PageName) --component (ComponentName)

You may provide the flags in either order, and in shortened form:

imu new -p (PageName) -c (ComponentName)

At some point, you will want to start again with a fresh page:

imu new -p (NewPageName)

Names should not contain spaces and should be valid as an HTML ID tag. These commands generate a new set of files to edit inside client/pages/(PageName).

Layout

Page Structure
components/*.js Component code.
license.html License comment tag; prepended to the page.
root.html Entry point into the page's actual DOM code.
root.css Entry point into the page style.
root.js Entry point into the page code.

Each page is given a components/ directory to hold Stage0 component JS, HTML templates and assorted JavaScript code specific to the page.

Most editing will be done on root.js and its child components/*. When you need to embed resources into the actual DOM, such as inlining SVGs and templates, you would edit root.html.

JS, CSS and HTML import directives will all search for paths relative to the importing file. In addition, it will also search the subdirectories of client and client/pages. The use of file extensions is optional except to resolve conflicts.

The compiled page files are placed in deploy/client.

Project Structure
client/pages Code for each application page.
client/share Code shared between each application page.
client/style Style code and Tailwind configuration.
client/svg SVG icons available for inlining.
client/util Third-party libraries used by application pages.
deploy/client The destination of compiled pages.
deploy/static All static files and content, available via /static
tmp Temporary files created during the build process.

The client/style directory contains the tailwind.config.js file and is a good place for stylesheets you wish to @import into pages. For example, a site may consist of many pages all importing the same set of Tailwind components. As each page has its own CSS file, you may safely place unique classes and overrides into it without affecting the styling of other pages.

The style/base.css file is the project-wide style reset. It is mostly the same as TailwindCSS's reset, using sections of Normalize.css, SUIT CSS and TailwindCSS-specific rules. It has had a few additional rules added, including part of Eric Meyer's reset.

If you need to use third-party ES6 modules that are not available via npm, use the client/util directory.

Static files should be placed in deploy/static. A built-in favicon.ico generator will place one inside deploy/static if one is not present when calling imu new -p. This is a 43 byte 1x1 transparent GIF image, as small as it can be made.

A suggested directory is client/share, to be used for components that are shared and imported across pages. For example, a '404 Not Found' component may be the same across all of your pages. You will need to create the client/share directory, should you choose to use it.

Other potential paths could include things such as client/store and client/api for holding modules for S.js store and API request related abstractions. client/router.js could hold your application's router configuration. These paths require no specific support from imu.

Bundling

JavaScript is bundled with Rollup.js, offering you ES6-level modules your page. For release builds, Terser is used to minimize the compiled page bundle with full ES6 support.

CSS is processed with PostCSS, with CSS Import and PostCSS Preset Env, which provides a number of current CSS spec features. PostCSS Preset Env also runs a pass with Autoprefixer, saving you from writing vendor-specific prefixes. For release builds, all unused CSS classes are automatically purged from the resulting code using PurgeCSS. CSSO is used as a final pass to minimize the code.

On release builds, the final HTML is run through HTMLMinifier prior to compression with gzip.

Preprocessor Directives

imu provides a set of directives available for use within files being built. For HTML it is: @import, @script and@svg.

The @import directive must be enclosed in a comment tag. The path provided should be relative to the current file path. This will copy the contents of the file into its place place.

A @script directive has also been included, which behaves the same as @import but will wrap the results in <script type="x/templates"> tags. An ID based upon the filename is included in these tags. As such, filenames must consist only of valid ID characters and should not contain spaces.

<div>
  <!-- @import "./local/project/file.html" //-->
</div>
SVG

An @svg directive has also been provided. It is used just like @import and @script.

SVG files imported will first be parsed and processed to add an ID based upon the filename, sans extension. The same restrictions on naming that apply to @script also apply here.

Furthermore, the fill attribute is set to 'inherit' and any height or width attribute is removed prior to inlining.

Server Overview

Optional .NET Core 2.1 and MySQL support is provided as follows:

* `imu server` builds the server project natively & SQL schema.
* `imu server-linux` builds the server project specifically for Linux.
* `imu sql` builds the SQL schema.

Copying configuration files, including nginx is done by:

* `imu copy-conf` Copies all server-related configuration into 'deploy/'.

Furthermore, new has the following additional commands:

* `imu new --server ServerName` starts a new server codebase.
* `imu new --table Name` starts a new SQL table file.
* `imu new --patch` starts a new SQL migration patch file.

Neither .NET Core 2.1 or MySQL build support makes use of tup.

SQL Preprocessor

An equivalent of @import has been added for MySQL and is used much the same.

# @import "./local/table/name"

Resetting

Should any issues with build artifacts arise, you may always try imu reset.

This will remove all build artifacts from the project. As your project expands, you may wish to update the list of files reset will remove in ./.imu/reset.js.

License

Dual-Licensed. Pick one. Pick both. Pick carefully.

imu is available as Jollo LNT or CC0 | Public Domain, as you desire. Either way, you may make full use of the included files for any reason, without attribution should you wish to leave no trace.

As imu aggressively strips code, including the original copyright comments, the relevant copyright notices are added as a document comment to all pages built for release. Be sure to keep license.html up to date as you change libraries.

You can’t perform that action at this time.