External Packages
This page discusses how to add new dependencies with yarn.
Be cautious of adding new dependencies, which introduce an indefinite maintenance burden.
Do not add packages via script tags. An external package’s documentation may show how to include it via script tags, for the sake of getting up and running quickly. This is fine to do in development. However, when added to production, packages should be installed via yarn. Virtually any package that would be added to HQ will be on NPM. In rare cases, we also include packages directly from GitHub, as described below. Using yarn enables tooling to do things like scan for outdated versions and for packages with recently discovered CVEs.
Yarn
Yarn can manage components that contain HTML, CSS, JavaScript, fonts or even image files. Yarn doesn’t concatenate or minify code or do anything else - it just installs the right versions of the packages you need and their dependencies.
Yarn packages
Yarn packages can be installed from a variety of sources, including a
registered yarn package (a repo that has a package.json file
defined), a Github shorthand (<user or org>/<repo_name>), a Github
URL, or just a plain URL that points to a javascript file.
When you install a package, it will be installed in a directory called
node_modules. For example if you were to run yarn add jquery,
you would find a directory node_modules/jquery.
Specifying packages in package.json
To ensure a package gets installed for a project, you must specify it in
the package.json file. This is equivalent to the
pyproject.toml file for Python with uv. Similar to uv sync for
python, for yarn, use yarn upgrade When specifying a yarn package
you can use many techniques. Here are a few examples:
// Installs the jquery package at version 1.11.1 to `node_modules/jquery`
"jquery": "1.11.1"
// Because `jquery-other` does not refer to a yarn package we must specify it in the
// versioning. Yarn will install this package to `node_modules/jquery-other`.
"jquery-other": "npm:jquery#1.2.0"
// This will install jquery from a github hash
"jquery-github": "jquery/jquery#44cb97e0cfc8d3e62bef7c621bfeba6fe4f65d7c"
To generalize, an install declaration looks like this:
<name>:<package>#<version>
Where <package> is optional if <name> == <package>. A package
can be any of these things:
Type |
Example |
|---|---|
Registered package name |
jquery |
Git endpoint |
|
Git shorthand |
user/repo |
URL |
There are more, but those are the important ones. Find the others here
A version can be any of these things:
Type |
Example |
|---|---|
semver |
|
version range |
|
Git tag |
|
Git commit |
|
Git branch |
|
Using Yarn packages in HQ
To use these packages in HQ, you can typically just import the name of the package.
The library’s package.json will have a main attribute that will signal to
Webpack which code to include.
Importing the library names rather than a specific file is more robust to library upgrades.
In ESM modules:
import DOMPurify from "dompurify";