Problem Statement

  • When working in enterprise environments, you often need to use private NPM registries like Nexus SonaType Repository Manager instead of the public npmjs.org registry.
  • Bun CLI needs to be configured to route package requests through your organization’s Nexus NPM proxy repository.
  • This article shows how to configure Bun to use a Nexus NPM proxy repository via bunfig.toml.

Goal

By the end of this article, you’ll be able to:

  • Configure Bun CLI to use Nexus SonaType NPM proxy repository.
  • Set up authentication for private repositories.
  • Verify the configuration is working correctly.

Tools Used

  • Bun: Fast JavaScript runtime and package manager.
  • Nexus SonaType Repository Manager: Enterprise artifact repository manager with NPM proxy support.

Steps

  1. Locate or Create bunfig.toml

    Bun reads its configuration from bunfig.toml. The configuration file can be located at:

    • Project level: ./bunfig.toml (in your project root)
    • User level: ~/.bunfig.toml (in your home directory)
    • Global level: $BUN_INSTALL/bunfig.toml

    For this guide, we’ll use the user-level configuration file.

    touch ~/.bunfig.toml

  2. Configure NPM Registry

    Add the following configuration to your bunfig.toml file to point Bun to your Nexus NPM proxy repository.

    ⚠️ VERY IMPORTANT: The Nexus SonaType NPM Proxy URL must end with a trailing slash (/). Without the trailing slash, Bun CLI will not work correctly.

    Content for ~/.bunfig.toml

    [install]
registry = "https://your-nexus-server.com/repository/npm-proxy/"

    Replace https://your-nexus-server.com/repository/npm-proxy/ with your actual Nexus NPM proxy repository URL. Remember to include the trailing slash at the end!

  3. Configure Authentication (if required)

    If your Nexus repository requires authentication, you’ll need to configure credentials. Bun supports authentication via .npmrc file or environment variables.

    Option A: Using .npmrc file

    Create or update ~/.npmrc with your Nexus credentials:

    //your-nexus-server.com/repository/npm-proxy/:_authToken=YOUR_AUTH_TOKEN

    Or using username/password:

    //your-nexus-server.com/repository/npm-proxy/:username=your-username
//your-nexus-server.com/repository/npm-proxy/:_password=base64-encoded-password

    Option B: Using environment variables

    You can also set authentication via environment variables:

    export NPM_CONFIG_REGISTRY="https://your-nexus-server.com/repository/npm-proxy/"
export NPM_CONFIG_AUTH_TOKEN="YOUR_AUTH_TOKEN"

  4. Verify Configuration

    Test that Bun is using your Nexus repository by installing a package:

    bun install express

    You should see the package being downloaded from your Nexus repository. You can also check the network requests in your Nexus server logs to confirm.

Example Configuration

Here’s a complete example of ~/.bunfig.toml for a Nexus NPM proxy:

Note: Notice the trailing slash (/) at the end of the registry URL - this is required for Bun CLI to work correctly.

[install]
registry = "https://nexus.example.com/repository/npm-proxy/"

And corresponding ~/.npmrc for authentication:

//nexus.example.com/repository/npm-proxy/:_authToken=npm_xxxxxxxxxxxxxxxxxxxx

Final Words

  • ⚠️ CRITICAL: The Nexus NPM proxy URL must end with a trailing slash (/) - Bun CLI will fail without it.
  • Ensure your Nexus NPM proxy repository is properly configured and accessible before setting up Bun.
  • For organization-wide deployment, consider using the global bunfig.toml location or environment variables.
  • Keep your authentication tokens secure and never commit them to version control.

If you have any feedback/issues, you can submit an issue in site repo.