Node Packages (npm)

A Node project is a folder with a package.json file in it. The packages the project uses are installed into a node_modules folder beside that file by a tool called npm. Circuitry does not install them itself: it opens a terminal on the computer that holds the project and runs npm there, where you can watch it.

For Python packages, see Installing Python Packages.

The npm button

npm is in the footer of the code editor. Press it for a short menu:

• Install packages runs npm install, which installs everything package.json lists. Do this once after you get a project from somewhere else.
• Add a package… asks for a name, then runs npm install with that name. The package is added to package.json too.
• Terminal in this project opens a terminal in the project's folder and runs nothing.

Each one opens a new terminal tab, named after the command. When the command ends, the terminal stays open in the project's folder, so you can read what npm said and type more commands.

When the button appears

The button appears when both of these are true:

1. The file is in a Node project. Circuitry looks for package.json in the file's folder, then in each folder above it. The first one found is the project, and its folder's name is shown at the top of the menu.
2. The file is on a computer that can run npm: this computer in the desktop app, or a computer you reach through a Circuit.

It does not appear:

• On a file with no package.json in any folder above it.
• On a file kept on a phone or tablet itself. npm cannot run there.
• On a file opened through a storage connection such as FTP or SFTP.
• On a pictures.js scene, even inside a Node project. A scene cannot use an npm package (below).

The button uses npm. For a project that uses pnpm or yarn, choose Terminal in this project and type the command yourself.

Add a package

1. Open any file in the project.
2. Press and choose Add a package….
3. Type the package's name, for example framer-motion, and press Install.
4. A terminal tab opens and npm runs. Wait for it to finish.

You can type several names with spaces between them. You can ask for a version (zod@3.23.8), and add -D for a package only needed while developing (vitest -D). Anything else is refused with a message such as "Upper" is not a package name: npm names are lower case, and nothing but names, versions and -D is accepted here. For any other npm command, use Terminal in this project.

Where it runs

If the Circuit disconnects while the file is open, pressing a menu item shows a Terminal dialog that says a computer is needed. Connect the Circuit again and try once more.

Using a package

In a React file's preview

A .jsx or .tsx file shows a live preview beside the code. The preview reads the project's node_modules, so an installed package works with an ordinary import:

import { motion } from 'framer-motion'

export default function Card() {
  return <motion.div animate={{ opacity: 1 }}>Hello</motion.div>
}

• After installing a package, press to build the preview again.
• If a package is imported but not installed, the preview still builds, with a placeholder where that package's parts would be. Install the package, then build the preview again.
• React itself is built into Circuitry. A React file with no node_modules at all, such as one saved on an iPad, still previews. Other packages need a project on a computer.

In a script you run with Node

Run in the footer runs a JavaScript or TypeScript file inside Circuitry, on the device in your hands. That is quick and needs nothing installed, but it is not Node, so it cannot load packages:

• A file with require(...) stops with require() is not available in browser.
• A file with import or export stops with ES modules (import/export) require Circuit execution.

To run a script that uses packages, run it with Node in a terminal:

1. Press and choose Terminal in this project.
2. Type node and the file's name, for example node scripts/report.js, and press Enter.

Scripts named in package.json run the same way: npm run build, npm test.

In a web page

An .html file's preview loads the scripts and styles the page names by their paths, the way a browser does. It has no bundler, so import x from "some-package" in a page's script is not found. A page can use a script file beside it, by its path: <script src="app.js"></script>.

To build a page from packages, use a React file, or run the project's own build in a terminal.

In a pictures.js scene

A pictures.js scene is a plain script that draws. It cannot use npm packages, and the npm button is not shown on one:

• An import or require( line means the file is no longer a scene, and its drawing preview goes away.
• The preview is shut off from the rest of your project. It loads its own drawing library and the files beside the scene, and nothing from node_modules.

What a scene can use instead:

• A file of your own beside the scene. await use("helpers.js") loads another .js file and hands back what it exports.
• three.js, which is built in: use THREE and addons.OrbitControls with no import.
• A library at a web address, with await use("https://…"). Circuitry asks before the scene may call that site.

See Files and libraries and what a scene can reach.

When it doesn't work

• No npm button: check that a package.json is in the file's folder or one above it, and that the file is on a computer (the desktop app, or through a Circuit), not on the phone or tablet itself. A new project needs package.json first: open a terminal from the menu, go to the folder and type npm init -y.
• The terminal says npm: command not found: Node is not installed on that computer. Install it from nodejs.org, then try again.
• The install fails part way: npm's own message in the terminal says why. The terminal stays open so you can read it and run the command again.
• The preview does not show the new package: wait for npm to finish, then press .

Related

• Code IDE Tour
• Terminals
• Circuit
• Installing Python Packages
• Languages, and where they run