Getting Started

There are many different ways to build components using Metal.js. You can use the built-in integrations with soy or JSX templates, or even build your own template abstraction on top of Metal.js and use it instead. You can build the ES6 code using babel, traceur or any other transpiler. You can test using karma, jasmine or any other test framework, and can use any directory structure for your project. To sum it up, you can customize everything to your own needs. The world is your oyster.

This guide will focus on a quick and easy way to get started with Metal.js. But if you are excited to try it out as soon as possible you can just play around with this JSFiddle.


You can organize your Metal.js project in any way you want, but to start out we recommend using the Yeoman generator we've created, which prepares both the project structure as well as a basic development workflow for you.

You can use it if you wish, but to makes things even simpler we're providing a zip with the boilerplate that the generator would create for this tutorial, so you can just download it here:

Note that this zip you've downloaded contains not only the starting boilerplate, but also a folder for each step of this tutorial guide, so that you can either code along with us or just check out the final code for each step.

Now that you have the boilerplate, you just need to:

  1. Install NPM v3.0.0 or newer (if you don't have it yet)

  2. For soy users only: Install Java version 8 or newer (if you don't have it yet)

  3. Enter the 1. Hello World folder in your terminal and install its npm dependencies, by typing: [sudo] npm i

Once the dependency installation ends, you'll get a directory tree similar to this:


If you open the generated src/Modal.js file you may notice that it's using ES6 syntax:

That means that it'll need to go through a build process, since browsers haven't fully implemented all ES6 features yet.

generator-metal already prepares some useful scripts that you can use, including a build script. By default, this script will build everything into global variables. To use it, simply type: npm run build

Demo Page

Now that the code was built, just open the generated demos/index.html file on your browser. It should display a nice Hello World message, like this:

If you look at demos/index.html's contents you'll see how the component is being rendered. In this example, it's simply being instantiated directly by calling new metal.Modal();.

By default this will append the component to the document's body. If you want though, you can specify where it should be rendered. Check the guide about rendering components to find out how.

Hello World

As you've noticed, the generated project automatically renders Hello World for you. Curious to see how that's done? It's simple, just take a look at the generated template:

You can replace the default content with any other to change what your component renders. Just make sure to build the code again after making your changes.

Next steps

Now that you have gone through running a simple Hello World component, let's actually turn it into a Modal.

↪ Tutorial: Modal