# Packages and libraries

Install NPM libraries, import them in TypeScript, and restore project dependencies.

URL: https://webrad.atentor.com/docs/packages
Updated: 2026-11-07

Install browser-compatible NPM libraries for use in Pages, Reusable Components, Models, and Units. Each project keeps its own dependencies.

## Requirements

Install **Node.js 20 or newer** and **NPM 10 or newer**, available on the system PATH. This also applies to the packaged WebRAD IDE. Save the project before opening its package manager. Missing tools are reported in the dialog.

## Install a library

1. Open **Project → Packages** or **Packages** in Project Explorer.
2. In **Search NPM registry**, enter a package name and click **Search**.
3. Review the matching package and click **Install**.
4. Wait for the operation to finish. The package appears in **Installed**, with its installed version.

To choose a version directly, use **Install by name**: enter the **Package name**, optionally fill **Version (optional)**, then click **Install**. Scoped names such as `@scope/package` are supported. Leave the version blank to install the registry's latest version.

The dialog shows requested, installed, and available latest versions, plus progress, process output, and errors. A cancelled installation can leave dependencies incomplete; use **Restore dependencies** before compiling again.

## Example: format a date with dayjs

Install the package `dayjs`. Choose **Project → Add Unit**, name it **Clock**, and edit `units/Clock.ts`:

```ts
import dayjs from 'dayjs';

export function formattedNow(): string {
  return dayjs().format('YYYY-MM-DD HH:mm:ss');
}
```

In a page's authored TypeScript file, add the import above the existing class. This example uses a Button named **Button1** and a Label named **Label1**:

```ts
import { formattedNow } from '../units/Clock';
// Keep the page's existing imports and class.
// Inside the linked Button1 OnClick method:
Label1.caption = formattedNow();
```

Link the button's **OnClick** in Interaction, copy the assignment into its method, and run **F9 Preview**. The Label displays the time when clicked. The relative import above assumes the authored page file is in `pages/`; adjust it if importing from another folder.

Project and package examples depend on the named Unit or installed package. The documentation editor displays and lets you copy them; it does not install packages or run the application.

## TypeScript support

After installation, Monaco reads the package's declarations for completion, hover, signatures, and diagnostics. If a package has no declarations, install its corresponding `@types/package` when available.

Use **Go to Definition** or Ctrl+click (Cmd+click on macOS) on an imported symbol to open installed declarations in a read-only viewer. F12 retains WebRAD's Design/Code switching behavior.

## Update, remove, and restore

| Action | Result |
| --- | --- |
| Update | Updates that direct dependency and its installed declarations. |
| Remove | Removes the direct dependency. Remove or replace its imports in your source as well. |
| Restore dependencies | Reinstalls the saved dependency tree; uses the lockfile when one exists. |

Save the project after changing dependencies. Keep the entire project folder, including the `.wrproj`, `package.json`, and `package-lock.json`, when copying it or using version control. `node_modules` is local installation data. Opening or moving a project does not silently install packages; open Packages and restore them explicitly.

## Preview and distribution

Preview, Debug, Web/PWA, and native frontends use the project's installed packages. Imports are bundled with the application; compatible CSS imports join its stylesheet. Exported browser applications do not need Node.js or a server-side `node_modules` folder to run. Native applications execute these libraries in the Tauri WebView.

Choose libraries that support the browser. Node-only modules such as `node:fs` and `child_process` are unavailable in application code. Network, CORS, workers, and other browser requirements still apply. Installation lifecycle scripts are disabled, so packages that require those scripts are unsupported by this manager.

The built-in module names `@webrad/*`, `pdf-lib`, `shaka-player`, and `@pdf-lib/standard-fonts` are reserved. Import their supplied APIs rather than trying to install replacement versions through Packages.

## Common problems

| Symptom | What to check |
| --- | --- |
| Node or NPM is unavailable | Install the required tools, make them available on PATH, and reopen the IDE if its environment needs refreshing. |
| A saved dependency is missing | Use Restore dependencies in Packages. |
| Cannot find a module | Check the name, installation result, and import path. |
| Missing declaration error | Look for the library's own types or its matching `@types` package. |
| An import fails after Remove | Remove or replace that import in the authored code. |
| A library requests a Node API or install script | Use a browser-compatible alternative. |

See [Global functions](https://webrad.atentor.com/docs/globals#create-shared-functions-in-a-unit) to organize shared application logic and [Web and PWA builds](https://webrad.atentor.com/docs/build-web-pwa) to export it.