Skip to content

Getting Started

Jump to bottom
Dominic Barnes edited this page Jul 1, 2017 · 1 revision

This guide will step you through setting up a simple front-end project using mako-browser. This is meant to be a shallow introduction, but hopefully enough to propel you to exploring other possibilities.

The first thing we'll do is install the CLI:

$ sudo npm install -g mako-cli

We're installing it globally in this case, which is just for the sake of simplicity. Many workflows with npm and node prefer installing dependencies locally, as it is much easier to deal with individual projects that way.

Next, let's create a few entry files. These are the files that we will start from when we begin resolving our dependency tree.

Let's start with an index.js:

console.log('Hello World');

And then let's create an index.css:

html {
  background-color: black;
  color: white;
}

Lastly, let's create a static index.html. This file is not an entry file and won't be passed to mako, but it will be useful when we go to see our JS and CSS in action.

<!DOCTYPE html>
<html>
  <head>
    <title>Hello World</title>
    <link rel="stylesheet" href="build/index.css">
  </head>
  <body>
    <h1>Hello World</h1>
    <script src="build/index.js"></script>
  </body>
</html>

Now, let's open up our HTML file:

# mac
$ open index.html

# linux
$ xdg-open index.html

You'll notice nothing fancy, since we haven't run any builds yet. Let's fix that! We'll start by creating a .makorc file:

{
  "entries": [
    "index.{js,css}"
  ],
  "plugins": [
    "mako-browser"
  ]
}

You'll notice we've added index.{js,css} to entries, which is just a pattern that is expanded for us. (the usual * glob patterns are supported as well) In this case, it will use index.js and index.css as our default entries.

In addition, we've added mako-browser to our plugins list. Since this is a plugin, we'll need to install it. (don't worry about setting up a package.json)

$ npm install mako-browser

Unless you are nested within another node project, this should create a node_modules directory with mako-browser installed.

Now we can run our build!

$ mako

If all went well, you should see:

info:    Build Complete! ✔

Let's go back to our web browser, now refresh the page.

All right! Now the colors have inverted, which means our CSS has worked correctly. Now, let's open up the console. If we see "Hello World" there, that means our JS is working correctly too!

Let's go ahead and make a change to our index.js file. Instead of printing to the console, let's dynamically update the text of our <h1> element. I want to make sure this is cross-browser, so let's install a helpful npm module:

$ npm install text-content

The mako-browser plugin allows us to use npm modules in both our JS and our CSS. (check out the mako-browser docs for more information) Now, let's update our index.js to use that module:

var text = require('text-content');
var h1 = document.querySelector('h1');
text(h1, 'Hello Mako');

Now, our JS should change the <h1> to say "Hello Mako" instead of "Hello World". Let's rebuild:

$ mako index.js

You'll notice that we specified index.js this time. This tells mako that you only want to build index.js, so it will leave index.css alone. (since we know there are no changes)

Go back to the browser and refresh. Voila! We should now see "Hello Mako". Thus concludes our introduction, which I hope helped explain the basics in a clear way. Feel free to open up an issue if there is something that you still don't understand or if there's something you'd like added.

Next, check out the Plugins page to look for more plugins that might fit your workflow. Each of those plugins should be well documented, detailing what sorts of features they offer.

If you don't see a tool that you need, you can always create a plugin of your own. Check out the Guide to Making Plugins page for information to get started in that regard.

Clone this wiki locally