Getting Started with the Closure Library

Stay organized with collections Save and categorize content based on your preferences.

This Hello World exercise introduces the process of using the Closure Library in a web page. To do this exercise you need to have some familiarity with JavaScript, as well as a Git client and Node.js.

Hello Closure

To get started with the Closure Library, use Closure JavaScript functions in a simple web page by following these steps:

Step 1: Download and Setup the Closure Library

Download the Closure Library from the Git repository by executing the following command from the command line: 

git clone https://github.com/google/closure-library

You need a Git client to execute this command, but you may already have one. Try the command, and if it doesn't work download and install a Git client.

After executing this command you should have a directory named closure-library that contains the Closure Library code.

Before continuing, the Closure Library repository must be initialized. Part of this exercise relies on a file named deps.js, which is generated (and therefore not part of the repository when it is first checked out). To generate this file, enter this directory and run npm install (npm is bundled with Node.js): 

cd closure-library
npm install

Step 2: Create a JavaScript file that uses the Closure Library

Save the following JavaScript in a file called hello.js. Place this file next to the closure-library directory. 

goog.require('goog.dom');
goog.require('goog.dom.TagName');

function sayHi() {
  var newHeader = goog.dom.createDom(goog.dom.TagName.H1, {'style': 'background-color:#EEE'},
    'Hello world!');
  goog.dom.appendChild(document.body, newHeader);
}

Step 3: Create an HTML file

Save the following HTML in a file called hello.html. Place this file next to the closure-library directory and the hello.js file. 

<html>
  <head>
    <script src="closure-library/closure/goog/base.js"></script>
    <script src="hello.js"></script>
  </head>
  <body onload="sayHi()">
  </body>
</html>

Step 4: Say Hello to the Closure Library

Open the HTML file in a browser. You should see the words "Hello world!":

How Does This Example Work?

The hello.js JavaScript uses two functions it doesn't define: goog.dom.createDom() and goog.dom.appendChild(). Where do these functions come from?

These functions are defined in the Closure Library that you downloaded in Step 1, in the file closure-library/dom/dom.js.

To make use of these functions, the example does two things:

  • It includes the statement goog.require('goog.dom') at the beginning of the JavaScript in Step 2.
  • It includes the Closure Library bootstrap file base.js in the HTML in Step 3.

The base.js file defines the function goog.require(). The function call goog.require('goog.dom') loads the JavaScript file that defines the functions in the goog.dom namespace, along with any other files from the Closure Library that those functions need.

The Closure Library loads these files by dynamically adding a script tag to the document for each needed Closure Library file. So, for example, the statement goog.require('goog.dom') causes the following tag to be added to the document, where path-to-closure is the path from the HTML file to the directory that contains base.js: 

<script src="path-to-closure/dom/dom.js"></script>

Typically a single goog.require() statement will load only a fraction of the Closure Library codebase.

Note: Do not put your goog.require() statements in the same script tag as the entry point to code that uses the goog.required functions or classes. A goog.require() call adds code to the document after the script tag containing the call. For example, this code works: 

<script src="closure-library/closure/goog/base.js"></script>
<script>
  goog.require('goog.dom');
</script>
<script>
  var newHeader = goog.dom.createDom(goog.dom.TagName.H1);
</script>

The goog.require() call adds the code for goog.dom.createDom() immediately before the script tag containing the line var newHeader = goog.dom.createDom(goog.dom.TagName.H1).

In contrast, the following code produces an error: 

<script src="closure-library/closure/goog/base.js"></script>
<script>
  // DON'T DO THIS.
  goog.require('goog.dom');
  var newHeader = goog.dom.createDom(goog.dom.TagName.H1);
</script>

This goog.require() call adds the code for goog.dom.createDom() in a script tag that won't be interpreted until after a call to goog.dom.createDom() has already been made.

Including base.js isn't the only way to include Closure Library code, but it is the easiest way to get started. No matter how you grab Closure Library code, however, you will always use goog.require() to declare the parts of the Closure Library that you need.

Next Steps

This example illustrates one way of getting just the parts of the Closure Library that you need: including base.js in your web page and calling its function goog.require().

For more advanced usage, the Closure Compiler is recommended to minify your JavaScript into a single file.