Home » Blog » How to Create and Publish an npm Scoped Package for Your Organization

How to Create and Publish an npm Scoped Package for Your Organization

An npm scoped package is a package named @scope/name, such as @bosctechlab/simple-calc-package. To publish one, create an org on npmjs.com, run npm init –scope, then npm publish –access public.

This guide is for developers who share code through an npm organization. You get the exact commands, the free vs paid rule, fixes for common publish errors and the current login rules.

At BOSC Tech Labs, our engineers created an npm org called bosctechlab and published a small calculator package to it for this guide. The core commands below come from that test run.

Key takeaways:

  • Every npm scoped package has a name like @scope/name, and only the scope’s owner can publish under it.
  • Scoped packages are private by default, so the first public publish needs –access public.
  • Public packages are free; private packages need a paid plan at $7 per user per month.
  • Publishing needs 2FA on your account, a granular token with 2FA bypass, or trusted publishing.

What is an npm scoped package?

An npm scoped package has a name that starts with @ and a scope, such as @bosctechlab/simple-calc-package. Only the user or org that owns the scope can publish under that name.

A scope works like a namespace. It groups related packages and shows everyone who maintains them. Scopes bring three practical benefits:

  • No name clashes: if calc-utils is already taken, @yourorg/calc-utils can still be free.
  • Only members of the scope can publish to it, so no one else can claim your package names.
  • You can point one scope at a private registry in .npmrc and leave every other package on the public registry.

Installed npm scoped packages live in node_modules/@scope/name, and you import them by their full name, scope included.

A user scope matches your npm username, while an org scope is shared by a team. If you are new to the CLI, our post on the difference between npx and npm explains running versus installing.

Before you start: npm organization, account and 2FA

Before you publish, you need Node.js and npm installed, an npm account with two-factor authentication turned on, and an org on npmjs.com whose name matches your scope.

Run node -v and npm -v to confirm both tools are installed. Any current Node.js LTS release ships with an npm version that supports everything in this guide.

npm now requires 2FA on your account, or a granular token with 2FA bypass, for every publish. Turn it on in your account settings before your first release, as npm’s 2FA guide explains.

A free org can publish unlimited public packages. You can create a new org, or convert your existing user account into one if you want your username as the scope.

Invite teammates from the org’s Members tab and add them to teams. Each team gets read-only or read-write access per package, and that access decides who can publish.

How to create and publish an npm scoped package in 6 steps

To publish an npm scoped package, create the org, create a scoped package.json, add your code, log in, preview the files, then publish and test the install.

These six commands cover the whole flow:

StepCommandWhat it does
Create package.jsonnpm init –scope=@bosctechlabNames the package @bosctechlab/…
Log innpm loginSigns you in with 2FA
Check accountnpm whoamiShows the logged-in user
Preview filesnpm pack –dry-runLists what will be published
Publishnpm publish –access publicPublishes the package publicly
Testnpm i @bosctechlab/simple-calc-packageInstalls it in another project

Keep this table nearby; the steps below explain each command with our real example.

Step 1: Create the organization on npmjs.com

Sign in at npmjs.com, open your profile menu and choose Add Organization. Pick a name and the free plan for public packages.

We named ours bosctechlab, so our scope is @bosctechlab. Anyone you invite to the org can later publish under that scope.

Step 2: Create a scoped package.json

Make a project folder and run npm init with your scope. npm writes the scope into the package name for you.

mkdir simple-calc-package && cd simple-calc-package
npm init --scope=@bosctechlab

Your package.json should look like this. The last field makes every publish public by default; the errors section below explains why that matters.

{
  "name": "@bosctechlab/simple-calc-package",
  "version": "1.0.0",
  "description": "Addition, subtraction and multiplication helpers.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "BOSC Tech Labs",
  "license": "ISC",
  "publishConfig": {
    "access": "public"
  }
}

Step 3: Add your code

Create index.js in the same folder and export your functions. Our package exposes three simple math helpers.

function addition(a, b) {
  return a + b;
}
function subtraction(a, b) {
  return a - b;
}
function multiplication(a, b) {
  return a * b;
}
module.exports = { addition, subtraction, multiplication };

Step 4: Log in and check your account

Run npm login. Recent npm versions open your browser, where you sign in and confirm with 2FA. Then check which account the terminal is using.

npm login
npm whoami

Step 5: Preview what will be published

Run a dry run before the real publish. It lists every file that would go into the tarball, the compressed archive npm uploads to the registry.

npm pack --dry-run

When our team ships a new package, we run npm pack –dry-run before every first publish. It lists each file that will go out, so a stray .env file or test folder is spotted early.

Step 6: Publish and test the install

Publish with the access flag. On npmjs.com, the label under the package name should now read public.

npm publish --access public

To test it, open another folder and install the organization-scoped package by its full name.

npm init -y
npm i @bosctechlab/simple-calc-package
Then require it in a file such as test.js and run it with node test.js.
const calc = require('@bosctechlab/simple-calc-package');
console.log(calc.addition(2, 3)); // 5
console.log(calc.multiplication(4, 5)); // 20

If the console prints 5 and 20, your package installs and works straight from the registry.

Public vs private scoped packages: access and cost

A public package is free and anyone can install it. A private package, which npm calls restricted, is visible only to people you grant access and needs a paid plan.

Here is how the two access levels compare:

AccessWho can installCostPublish commandLabel on npmjs.com
PublicAnyoneFreenpm publish –access publicpublic
Private (restricted)Org members or teams you grant access$7 per user per month (npm Teams)npm publish or npm publish –access restrictedprivate

For open source and shared tools, public is the simple choice; pick private only when the code must stay inside your team.

For client projects, we usually suggest keeping internal libraries private under the client’s own org, so package access stays with their team after our engagement ends.

Every npm scoped package starts as restricted, and you can change its visibility later. Use the package’s Settings page, or run npm access set status=public as described in the npm access docs.

Before you switch a private npm package to public, check it for keys and internal URLs. On npm Teams, the $7 fee applies to every org member, as npm’s paid organization plan page explains.

How to fix 402 Payment Required and other publish errors

The 402 Payment Required error means npm tried to publish your package as private on a plan without private packages. Add –access public, or set access to public in

package.json.
"publishConfig": {
  "access": "public"
}

With that publishConfig setting in place, a plain npm publish goes out as public, so no one on your team can forget the flag.

Other first-publish errors have equally quick fixes:

ErrorWhat it meansFix
E402npm is publishing your scoped npm package as private on a free planAdd –access public or set the access field in package.json to public
E404 Scope not foundNo user or org owns that scope, or you are not a memberCreate the org on npmjs.com or fix the scope in the package name
E403 ForbiddenThe version already exists, you lack permission, or 2FA is missingBump the version, check npm whoami and your team role, turn on 2FA
E401 / ENEEDAUTHYou are not logged in, or your token was revoked or expiredRun npm login, or create a new granular access token

Almost every one of these errors traces back to the scope name, the access level or your login.

On our projects, the first publish to a new scope is where things usually go wrong: a missing –access flag or an org that was never created. Both take about a minute to fix.

For the full rules on scopes, access and registries, see npm’s scope documentation.

How to publish from CI without long-lived tokens

Use npm trusted publishing. It lets GitHub Actions or GitLab CI publish your scoped npm package with short-lived OIDC credentials, so no npm token sits in your CI secrets.

In the CI/CD pipelines we build for clients, we prefer short-lived credentials over stored secrets wherever the platform allows it, and trusted publishing fits that rule well.

You set it up by linking the package to your repository and workflow file in its settings on npmjs.com. Publishes from that workflow can also carry provenance, a signed record of where the build ran.

If your CI platform is not supported, use a granular access token with a short expiry. Classic npm tokens were permanently revoked in late 2025 and no longer work.

npm’s trusted publishers guide covers the setup in full, and our CI/CD pipeline services cover release automation for client teams.

Frequently asked questions

Is publishing a scoped package on npm free?

Yes, for public packages. Publishing with –access public costs nothing, while private packages need a paid plan. Without the flag, a free account hits the 402 Payment Required error on its first publish.

Can I change a private npm package to public later?

Yes. Open the package’s Settings page on npmjs.com, or run the npm access set status=public command as an owner or team member with write access. Check the code for secrets before you switch.

What is the difference between a user scope and an npm organization scope?

A user scope matches your username, and only you can publish to it. An org scope is shared: members publish according to their team permissions, and owners manage billing and access.

How do I give a teammate publish access to our scope?

Invite your teammate to the org on npmjs.com and add them to a team. Then give that team read-write access to the package, and they can publish once their own 2FA is turned on.

Can I move an npm scoped package to a different scope?

Not directly, because the scope is part of the name. Publish the code under the new scoped name, then run the npm deprecate command on the old package with a message pointing to the new one.

Next steps after your first publish

Your first npm scoped package is live once the install test passes. From here, bump versions with npm version, write a clear README and move releases into CI.

Keep the access setting in package.json so public releases stay public, and review team access whenever people join or leave the org.

Need help with npm scoped packages, monorepos or release pipelines? Talk to our full-stack development team about your project.

    Get in touch


    Explore More