Skip to main content

Working with npm

npm is the standard package manager for web projects that use JavaScript. It allows you to install, manage, and share reusable packages of code. When you're building in Figma Make, npm is how external libraries and packages become available in your project.

This page covers what you need to know about npm to work effectively in Figma Make and Make kits. For a deeper look at npm itself, these resources are a good starting point:

Packages and dependencies​

A package is a bundle of reusable code that someone has published for others to use. Packages can be small and focused, like a library that formats dates, or large and comprehensive, like a full UI component framework.

When your project uses a package, that package becomes a dependency of your project. Dependencies are listed in a file called package.json, which lives at the root of a project. This file acts as a manifest. It describes which packages a project needs and which versions are acceptable. When you install a package, npm adds it to package.json and downloads the package code into a folder called node_modules.

// A simplified example of dependencies in package.json
{
  "dependencies": {
    "react": "^18.2.0",
    "lucide-react": "^0.300.0",
    "recharts": "^2.10.0"
  }
}

Packages are installed based on a version number. With npm, version numbers follow a format called semantic versioning (or semver), which looks like 1.4.2.

The three numbers represent major, minor, and patch versions. A major version change means there could be breaking changes. A minor version adds new features without breaking existing ones. A patch version includes bug fixes. The ^ symbol in front of a version number means "this version or any compatible newer version," which allows your project to receive minor updates and patches automatically.

Installing packages​

When you’re working outside of Figma Make, you use the npm install command followed by the package name to install a package. This downloads the package and adds it to your project's dependencies.

# Install a single package
npm install recharts

# Install a specific version
npm install react-hook-form@7.55.0

# Install multiple packages at once
npm install @emotion/react @emotion/styled
note

Note: You may also hear about yarn and pnpm. Similar to npm, these are package managers that you can use to install and manage packages. This article focuses primarily on npm, but you can read more about the other package managers here:

Some packages depend on other packages to function. These are called peer dependencies. When you install a package that has peer dependencies, you may need to install those additional packages yourself. For example, if you install @mui/material, you also need to install @emotion/react and @emotion/styled for it to work correctly. It’s good practice to read the documentation for the packages you’re using so you can be aware of dependencies.

In Figma Make, package installation is handled for you when the model adds a new library to your project. You can request that a specific package be installed by mentioning it in your prompt. You can also add packages directly to the package.json file that’s included in Figma Make files. For example:

  • “Use three.js for 3D motion graphics in the app.”
  • “Add @fortawesome/fontawesome-free for icons.”

Using packages in Figma​

In Figma Make, the model can install and use npm packages on your behalf as it builds your application. Common packages include lucide-react for icons, recharts for charts and graphs, and motion for animation. If you want a specific package used in your project, you can mention it by name in your prompt.

For Make kits, you’ll apply packages that have been uploaded to your Pro team or organization’s private npm registry.

In both cases, you can manually include additional packages by adding them directly to the package.json file that’s included in every Figma Make file.

When working with packages, keep these things in mind:

  • Packages must be installed before they can be imported. If you reference a package that isn't installed, you'll see an error.
  • Some packages require additional setup or configuration beyond installation. The package's documentation will describe any extra steps.
  • Package versions matter. If a tutorial or example references a specific version of a package, the API may have changed in newer versions.

To learn more about how packages can be used with Make kits, see:

Import statements​

Once a package is installed, you use import statements to bring its code into your files. There are a few common patterns for importing.

// Import specific named exports from a package
import { useState, useEffect } from "react";

// Import a default export
import Button from "./components/Button";

// Import everything from a package under a namespace
import * as React from "react";

Named exports let a package expose multiple values, and you pick the ones you need using curly braces. Default exports let a package designate a single main value, which you import without curly braces. A single package can offer both.

When you’re working with a package, you need to follow the method(s) the package uses. Most packages provide documentation that describes how you import code from the package. In the context of Figma Make, you can also ask Make to examine the package to determine how it needs to import code.

The string after from is called the module specifier. When it starts with ./ or ../, it refers to a file in your own project. When it's a plain name like "react" or "recharts", it refers to a package installed in node_modules.

// Importing from an installed package (no path prefix)
import { LineChart, Line, XAxis, YAxis } from "recharts";

// Importing from a local file (relative path)
import { Header } from "./components/Header";

Registries​

A registry is where packages are stored and downloaded from. The npm public registry at npmjs.com hosts hundreds of thousands of open-source packages. When you run npm install recharts, npm fetches the package from this public registry by default.

Organizations can also set up private registries to host packages that are only available to their team. Private packages work the same way as public ones. You install them, import them, and use them in your code just like any other package. The only difference is access: private packages aren't visible to the public, and you need to be authenticated to download them.

note

Figma provides private npm registries that can be used for uploading packages to your Pro team or organization.

In the context of the private npm registries provided by Figma, all npm packages you publish to Figma are Customer Content (see the Figma Terms of Service). Accordingly, Figma will only access, use, or process such npm packages in accordance with the purposes and limitations set forth in that agreement.

Private packages in the Figma npm private registries are hosted within the same AWS infrastructure that supports the Figma service. This infrastructure is subject to the same security, privacy, and compliance controls that govern the protection of other Customer Content within Figma.

Private packages often use a scoped name, which starts with @ followed by the organization name. For example, @figma/plugin-typings is a scoped package under the figma organization. Scoped names help avoid naming conflicts with public packages and make it clear where a package comes from. Not all scoped packages are private, though. Many organizations publish scoped packages to the public registry as well.

{
  "dependencies": {
    "recharts": "^2.10.0",
    "@figma/plugin-typings": "^1.80.0", // scoped package
    "@yourcompany/design-system": "^3.1.0" // scoped package
  }
}