A complete record of publishing moongate-vue from build to npm, including 2FA, WebAuthn, registry switching, and automation scripts.

This article covers: nrm registry management, 2FA configuration, WebAuthn setup, local linking for testing, automated release scripts, and a pre-publish checklist.

I. Introduction

After the component library is developed, the final and most critical step is: publishing to npm. This process may seem simple, but it hides many practical challenges: package name conflicts, mandatory 2FA, security key (WebAuthn) issues, and frequent registry switching.

This article, as the final installment of the series, documents every obstacle I encountered while publishing moongate-vue and their solutions.

II. Pre-Publish Preparation

2.1 Check Build Outputs

Before publishing, ensure the outputs exactly match the build matrix we designed in the third article:

# Build the component library
pnpm run build

# Check the dist directory
ls dist/
# Should see:
# - index.mjs   (ES Module, for modern bundlers)
# - index.cjs   (CommonJS, for SSR / Node)
# - index.d.ts  (TypeScript declarations)
# - style.css   (Bundled styles)

2.2 Verify package.json Distribution Contract

These fields determine how the host project correctly resolves your components:

{
  "name": "moongate-vue",
  "version": "0.0.1",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "sideEffects": ["*.css"],
  "peerDependencies": {
    "vue": "^3.0.0"
  }
}

💡 Bundle size tip: The files field is an allowlist. With ["dist"], npm will only upload the dist directory. package.json, README.md, and LICENSE are always included automatically.

2.3 Manage npm Registries with nrm

You must use the official registry to publish. If you previously switched to a mirror for faster downloads, use nrm for quick switching:

# Install nrm globally
npm install -g nrm

# List all available registries
nrm ls

# Add a mirror if missing
nrm add npmmirror https://registry.npmmirror.com

# Switch to the official registry (required for publishing)
nrm use npm

# Check the current registry
nrm current

2.4 Local Integration Testing

Before publishing to npm, test the library in a real project. My local testing workflow:

# 1. In the component library directory: build + link globally
pnpm build
pnpm link --global

# 2. In the test project directory: link the local library
pnpm link /absolute/path/to/moongate-vue  # Replace with your actual path

This approach doesn't require modifying the test project's package.json, and the link path is clear and controllable.

Testing checklist:

• [ ] Components render correctly
• [ ] Styles import correctly (import 'moongate-vue/style.css')
• [ ] TypeScript type hints work
• [ ] HMR works

Note: To completely remove the link after testing, manually delete the "moongate-vue": "link:../moongate-vue" entry from package.json, then run pnpm install to restore the normal version from npm. If you only need to temporarily break the link while keeping the configuration, remove node_modules and reinstall.

III. Tackling Two-Factor Authentication (2FA)

npm now requires 2FA for publishing to prevent supply chain attacks. npm has fully adopted the WebAuthn (Security Key) mode.

3.1 Browser Choice and Network Environment

⚠️ Important: npm's WebAuthn verification (e.g., Windows Hello or Touch ID) attempts to communicate with external verification services. In some network environments, the security key popup in Chrome/Edge may time out or fail to respond.

Make sure your network environment is stable and can reliably access external services before configuring or publishing.

3.2 Recommended: Configure Security Key via Web UI

1. Log in to npmjs.com.
2. Click avatar → Account → Two-Factor Authentication.
3. Choose Security Key (recommended, can use fingerprint or Face ID) or Authenticator App.
4. Follow the prompts to complete the setup.

3.3 CI/CD Automation Alternative: Granular Access Token

If you're publishing in a CI environment (e.g., GitHub Actions) or cannot pass 2FA locally (e.g., network restrictions), generate a Granular Access Token to bypass 2FA:

1. Log in to npm → click avatar → Access Tokens.
2. Select Generate New Token → Granular Access Token.
3. Grant Read and Write permissions.
4. Critical: check "Bypass two-factor authentication for automation".
5. Add the token to your local .npmrc:

//registry.npmjs.org/:_authToken=your_granular_token_value

IV. Standardized Publishing Workflow

Follow these atomic steps in order. Incorrect order may invalidate versions or cause publication failures.

4.1 Manual Publishing Steps

1. Lock the registry: Run nrm use npm to ensure the local registry points to the official source.
2. Login: Run npm login. Enter your username and password. The terminal will print an interactive URL for 2FA authorization.
3. Bump version: Run npm version patch|minor|major following semantic versioning.
   • npm version patch (bug fix, 0.0.7 → 0.0.8)
   • npm version minor (new feature, 0.0.7 → 0.1.0)
   • npm version major (breaking change, 0.0.7 → 1.0.0)
4. Publish: Run npm publish --access public. If your package name is scoped (e.g., @moongate/vue), the --access public flag is required.

4.2 Automated Release Script

Manual registry switching, version bumping, tagging, publishing, and switching back is tedious and error-prone. Here's a step-by-step release script in package.json:

{
  "scripts": {
    "release:pre": "nrm use npm && npm run build",
    "release:version": "npm version patch --no-git-tag-version",
    "release:tag": "git add package.json && git commit -m \"chore: release v$(node -p 'require(\"./package.json\").version')\" && git tag v$(node -p 'require(\"./package.json\").version')",
    "release:publish": "npm publish --access public",
    "release:post": "echo '✅ Done! To switch back to mirror, run: nrm use npmmirror'",
    "release": "npm run release:pre && npm run release:version && npm run release:tag && npm run release:publish && npm run release:post"
  }
}

Run npm run release. If any step fails, the process stops immediately — no leftover tags or unintended registry switches.

V. Pre-Publish Final Checklist

Before running the publish command, verify these items:

• [ ] Build succeeds: pnpm run build completes without errors.
• [ ] Artifacts complete: dist/ contains .mjs, .cjs, .d.ts, and .css.
• [ ] Types valid: dist/index.d.ts is non-empty and exports all component type contracts.
• [ ] Clean version: npm version has been run; the version number has never existed on npm.
• [ ] Local verification: Tested via pnpm link in a real project (see 2.4), confirming components render correctly and styles import properly.

VI. FAQ

Q1: 403 Forbidden or 404 Not Found on publish?

A: 403 usually means the package name is already taken, or you haven't run npm login (or your credentials expired). 404 means you forgot to run nrm use npm and are publishing to a read-only mirror.

Q2: Security key popup doesn't appear during 2FA?

A: This is usually a network issue. WebAuthn depends on external services. Confirm your network can reliably access these services. If still failing, use the Granular Access Token approach (section 3.3).

Q3: Styles don't load after installation (blank page)?

A: Two things to check:

1. Your package.json has "sideEffects": ["*.css"]. Without this, bundlers may tree-shake the CSS.
2. Users must explicitly import styles:

   import 'moongate-vue/style.css'

Q4: Local linked library updates don't take effect?

A: Rebuild with pnpm build, then re-link in the test project. If still not working, manually delete the link: entry from package.json, run pnpm install, then re-link.

VII. Conclusion

With the terminal output + moongate-vue@0.0.1, my Vue 3 component library is now available to developers worldwide.

From the design token specification in the first article, to the thin-wrapper philosophy, the type backtracking of complex components, and finally the industrial-grade npm distribution — five articles, one complete engineering cycle for a modern front-end component library.

Packaging and publishing is not the end, but the true beginning of a component library's lifecycle.

© 2026 yuelinghuashu. This work is licensed under CC BY-NC 4.0.