npm packages (JavaScript, TypeScript)

> Only want npm installs to be faster or to work when npmjs.com is out of reach? See [the npm mirror](/docs/en/package-mirrors#javascript-npm). **npm** installs JavaScript packages. It can send one *scope* (the `@name/` part of a package name) to a different registry than the rest, which is how Zaryn fits in: your `@you/...` packages come from Zaryn, everything else still comes from npmjs.com. ## Tell npm about Zaryn (once per project, or once per computer) Create a token on [Packages](/packages) (**Create a publish token**). Then put these two lines in a file called `.npmrc`, either in your project's folder or in your home folder (`~/.npmrc`) for every project: ```ini @your-username:registry=https://api.zaryn.xyz/v1/packages/npm/ //api.zaryn.xyz/v1/packages/npm/:_authToken=YOUR_TOKEN ``` - The first line: packages whose names start with `@your-username/` live on Zaryn. - The second line: the token npm sends to Zaryn. Don't commit a file with a real token into a public repository; npm also reads `${NPM_TOKEN}` from the environment if you write `_authToken=${NPM_TOKEN}`. Use your Zaryn username, or the name of an organization you own or administer, as the scope. ## Publish In `package.json`, give the package a scoped name and a version: ```json { "name": "@your-username/hello", "version": "0.1.0", "main": "index.js" } ``` ```bash npm publish --access public ``` Without `--access public`, npm asks for a **private** package (that's npm's rule for scoped names), which needs Premium. To publish a fix, raise `version` and publish again; a published version can't be replaced. ## Install With the `.npmrc` lines in place, install it like any other package: ```bash npm install @your-username/hello pnpm add @your-username/hello yarn add @your-username/hello ``` ## Install straight from a Zaryn repository Any commit of a repository with a `package.json` installs without publishing: the repository's **install** tab (next to the clone commands) gives the line: ```bash npm install https://zaryn.xyz/api/v1/repos/<owner>/<repo>/branches/main/archive/<commit>.tar.gz ``` It pins that exact commit, in `package.json` too. ## Private packages (Premium) `npm publish` without `--access public` creates a private package; you can also switch an existing one on its page (**Make private**). Only you, or members of the organization that owns it, can see or install it, using the same `.npmrc` token. ## When something goes wrong | npm says | What it means | Fix | |---|---|---| | `E401` | no token, or a wrong one | check the `_authToken` line in `.npmrc` | | `E403` "you can only publish under your own @username…" | the scope isn't yours | use your username or your organization's name | | `E402` "Private packages are a Premium feature" | a scoped publish without `--access public` | add `--access public`, or upgrade | | `E404` when installing an unscoped package | npm asked Zaryn for a package that lives on npmjs.com | only map your scope to Zaryn, as above | | `E409` "already published" | versions can't be replaced | raise `version` | ## How it works Zaryn speaks npm's registry protocol: the package document npm reads (versions, dist-tags, dependencies) and the `.tgz` files, each with its `sha512` integrity value, which npm checks on every install.