Using External Libraries

← back to Creative Computing

by Allison Parrish

There’s only so much functionality you can pack into a single programming framework, and while p5.js comes with a lot of goodies, it doesn’t come with everything. In this tutorial, I’ll show you how to locate, download and integrate third-party p5.js-compatible libraries.

Third-party libraries

A third-party (or “contributed”) library is a chunk of Javascript code, usually contained in a single .js file, designed to work with p5.js but that doesn’t come with p5.js by default. In this tutorial, we’re only going to talk about Javascript libraries that are specifically designed to work with p5.js. The p5.js folks maintain a list here, and there are also instructions on the p5.js wiki about contributing your own libraries.

The library we’re going to use in this tutorial is RiTaJS, a library by Daniel Howe and contributors for working with text.

A side note on JavaScript packaging

Feel free to skip this section if you’re not interested in the gruesome details.

As with all things JavaScript, there are a bajillion different ways to do the same thing, and unless you’re working with JavaScript every day, it can be difficult to keep track of what people are actually doing. The way that libraries are packaged and distributed is no exception. MDN has a good reference on ECMAScript Modules, which is (as of this writing) the latest iteration of JavaScript packaging/library syntax.

Other technologies you might end up using include:

  • RequireJS, a different standard for packaging JavaScript code, often used with Node.js
  • npm and yarn, two similar tools for finding and managing JavaScript libraries in your project
  • webpack and browserify, for bundling together packages
  • unpkg, a content delivery network for NPM packages (which also makes it possible to use many NPM packages in the browser without actually running NPM)

And frankly God knows what else. Many (if not most) browser-side JavaScript libraries still support the “classic” way of loading libraries: you download the library, include it as a <script> tag, and the library creates a global variable that you use to access the library’s functionality. We’ll assume that this is how you’re making use of libraries in the tutorial material that follows.

Downloading the library

To use a library, you have to “install” it in your sketch. The basic steps of installation are as follows:

  • Locate the correct Javascript download of the library you want to install.
  • Download the library and make a copy in your sketch folder. (If you’re using the web editor, you can upload the relevant files using Upload file in the dropdown in the “Sketch Files” sidebar.)
  • Add a <script> tag to your sketch’s index.html to include the library when your sketch loads.

Locating the Javascript download is usually a matter of going to the home page of the library and finding the “download” link. Sometimes you’ll be offered the choice between a “minified” version and a normal version. The “minified” version works exactly the same as the normal version, but it has undergone an “optimization” process to make the code smaller. (Read more about the process here.). It’s always safe to use the minified version, but because the minification process makes it difficult for humans to read the code, you might prefer to download the full-size version if you want to be able to examine the code to see what it’s doing.

The RiTaJS download page is here. Download the file labelled “Core Library via UNPKG” and remember where on your computer you downloaded the file. (You may need to right-click/ctrl+click and select “Save Link As…” to download the file instead of viewing it.)

Installing the library

Once you have the .js file, you need to put it in the same place as the rest of your project. For simplicity’s sake, put it in the same folder that your sketch.js is in. If you’re using the p5js web editor, use the dropdown menu in the side bar to select Upload file and then upload the library file from where you saved it earlier.

Modifying your HTML

Copying the file is just the first step. Next, you need to modify the index.html file of your sketch so that the library you just copied gets loaded by the browser before your sketch starts. The easiest way to edit your sketch’s index.html file is to activate the p5.js editor’s “sidebar,” which will then show a list of all files associated with your sketch on the side of your screen.

Select index.html in the sidebar. This is the web page associated with your sketch. The code for this page is automatically generated by the p5.js web editor when you create a new project. Normally, this code simply loads the p5.js default libraries and displays the sketch, but you can modify the code to do whatever you want. Here’s what the HTML contains by default:

<!DOCTYPE html>
<html lang="en">
<head>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/p5.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/addons/p5.sound.min.js"></script>
    <link rel="stylesheet" type="text/css" href="style.css">
    <meta charset="utf-8" />

</head>
<body>
    <script src="sketch.js"></script>
</body>
</html>

To install a library, you need to add the following line to the HTML file, right above the line that begins with <script src="sketch.js"...:

<script src="YOUR_LIB.js"></script>

… replacing YOUR_LIB.js with the filename of the library that you want to add (the one you just copied to the libraries folder). For example, after adding the <script> tag for RiTaJS, your index.html should look something like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/p5.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/addons/p5.sound.min.js"></script>
    <script src="rita.js"></script>
    <link rel="stylesheet" type="text/css" href="style.css">
    <meta charset="utf-8" />

</head>
<body>
    <script src="sketch.js"></script>
</body>
</html>

If you’re not using the web editor, make sure you upload your contributed library along with all of your other files!

Does it work?

Try out the following code to test if RiTaJS has been installed correctly:

► run sketch ◼ stop sketch 
let field;
let button;
function setup() {
  createCanvas(400, 300);
  field = createInput();
  button = createButton("Get rhymes!");
  button.mousePressed(findRhymes);
  background(50);
  textSize(32);
  noStroke();
  fill(255);
}
function draw() {
}
function findRhymes() {
  background(50);
  let rhymes = RiTa.rhymes(field.value());
  if (rhymes.length > 0) {
    text(rhymes.join(" "),
      10, 10, width-10, height-10);
  }
}

Type a word into the box and click “Get rhymes!” If RiTaJS recognizes your word, and knows of other words that rhyme with it, they will be displayed to the screen. Don’t worry if you don’t understand the code—I’ll explain it in more detail in this RiTaJS tutorial!

If it didn’t work, check the following:

  • Is the correct .js file in your sketch’s libraries folder? (Make sure that you copied it into libraries and not some other folder.)
  • Did you add the <script> tag? Check the syntax of the line to make sure it matches the example above exactly. (Is there a closing </script> tag? Did you match all of your quotes and angle brackets?)
  • Is the content of the .js file you downloaded correct? Open it up in a text editor and ensure that the file looks identical to the one on the library website. (You might have accidentally downloaded, e.g., the GitHub page for the library, instead of downloading the Javascript code for the library.)