Skip to main content

Using JointJS NPM Repository

This guide explains how to install JointJS packages from our private npm registry using your JointJS access token.

You will need:

info

No npm login is required.

Obtain access token​

If you are a trial user, you received your access token during the trial sign-up process. If you are a customer, log in to the customer portal at https://my.jointjs.com to obtain your access token.

note

Access to the npm registry is available while your subscription to JointJS updates is active. Once the subscription expires, registry access will be disabled, but you can continue using JointJS from the ZIP archive you can download from the customer portal.

Setup Dev environment​

Recommended (secure & flexible)​

1. Create a project-level .npmrc​

In the root of your project, create a file named .npmrc:

@joint:registry=https://npm.jointjs.com
always-auth=true
//npm.jointjs.com/:_authToken=${JOINTJS_NPM_TOKEN}

2. Set the token as an environment variable​

Define the JOINTJS_NPM_TOKEN environment variable in your terminal or CI environment.

macOS / Linux:

export JOINTJS_NPM_TOKEN="jjs-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Windows (PowerShell):

$env:JOINTJS_NPM_TOKEN="jjs-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

3. Install packages​

From now on, you can install JointJS packages as any other package:

npm install @joint/plus

Alternative setups​

User-level setup (~/.npmrc)​

If you want a “set once, forget” setup for your machine:

@joint:registry=https://npm.jointjs.com
always-auth=true
//npm.jointjs.com/:_authToken=${JOINTJS_NPM_TOKEN}

Then set JOINTJS_NPM_TOKEN environment variable in your shell profile.

note

This applies to all projects on your machine.

Quick start (token directly in .npmrc)​

For quick testing only (not recommended for production), you can place the access token directly in the _authToken field, for example:

@joint:registry=https://npm.jointjs.com
always-auth=true
//npm.jointjs.com/:_authToken=jjs-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This approach is not recommended, as it increases the risk of accidentally committing the token to source control.

warning

Do not commit this file if it contains the token directly.

info

Why the recommended setup uses an environment variable:

  • Keeps tokens out of source control
  • Makes token rotation easier
  • Works consistently across local development and CI environments

Setup CI environments​

This section provides examples for popular CI systems

GitHub Actions​

Add the following to your GitHub Actions workflow:

- name: Configure npm
  run: |
    cat > ~/.npmrc <<'EOF'
    @joint:registry=https://npm.jointjs.com
    always-auth=true
    //npm.jointjs.com/:_authToken=${JOINTJS_NPM_TOKEN}
    EOF
  env:
    JOINTJS_NPM_TOKEN: ${{ secrets.JOINTJS_NPM_TOKEN }}

- name: Install dependencies
  run: npm install

GitLab CI​

Add the following to your .gitlab-ci.yml:

before_script:
  - |
    cat > ~/.npmrc <<'EOF'
    @joint:registry=https://npm.jointjs.com
    always-auth=true
    //npm.jointjs.com/:_authToken=${JOINTJS_NPM_TOKEN}
    EOF

install:
  script:
    - npm install

Jenkins​

Follow these shell commands in your build step:

cat > ~/.npmrc <<'EOF'
@joint:registry=https://npm.jointjs.com
always-auth=true
//npm.jointjs.com/:_authToken=${JOINTJS_NPM_TOKEN}
EOF

npm install

Access token lifecycle​

  • Trial tokens may expire automatically.

  • Production tokens can become inactive when your subscription to JointJS updates expires and is not renewed.

  • When you receive a new token, just update your environment variable:

    JOINTJS_NPM_TOKEN="jjs-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    • No other config changes are required
    • Registry URL and package names stay the same

Using JointJS packages in package.json​

Once your npm registry is configured, you do not need any special configuration in your package.json beyond declaring the dependency.

Add JointJS packages as normal dependencies:

{
  "dependencies": {
    "@joint/plus": "^4.2.1",
    "@joint/format-visio": "^4.2.1"
  }
}

Then run:

npm install

NPM will automatically resolve @joint/* packages from https://npm.jointjs.com based on your .npmrc configuration.

Switching from trial to production​

When you move from a trial to a paid subscription, the only thing that changes is your access token.

You do not need to change:

  • your registry URL (https://npm.jointjs.com)
  • your .npmrc scope configuration
  • your package.json dependencies (@joint/*)
  • your lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb)

Steps to switch to production​

  1. Obtain your production access token (from the customer portal at https://my.jointjs.com).
  2. Replace the token used by your environment variable or .npmrc.

If you use an environment variable (recommended):

export JOINTJS_NPM_TOKEN="jjs-PRODUCTION-TOKEN"
npm install

If your CI stores the token as a secret, update the secret value and re-run the pipeline.

Optional cache invalidation​

The package managers may cache metadata and tarballs. If you encounter unexpected behavior after changing tokens:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

That’s it. The same project configuration will now install production packages using the new token.

Common issues & troubleshooting​

ENEEDAUTH or 401 Unauthorized​

  • Ensure always-auth=true is present
  • Verify JOINTJS_NPM_TOKEN is set in the environment
  • Restart your terminal or CI job after setting the variable

NPM is still trying to use registry.npmjs.org​

  • Check that your package name is scoped (@joint/...)
  • Verify .npmrc is in the project root (or ~/.npmrc)

Cached failures​

NPM can cache auth failures if you changed tokens.

  • Clear the cache

    npm cache clean --force

Security best practices​

  • Prefer environment variables over hard-coded tokens (see why)
  • Use different tokens for CI vs developer machines
  • Rotate tokens immediately if leaked (visit customer portal at https://my.jointjs.com to rotate your token)

Need help?​

If you run into any issues, contact JointJS support and include npm console log to your question.

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub