Skip to main content

Publishing NPM Packages

At Space 48, we use different namespaces and registries for our packages depending on their intended use.

Package Namespacing​

We maintain two different namespaces:

  • @space48/* - For publicly available packages published to NPM (see Open Source NPM Publishing)
  • @space48-internal/* - For internal tooling and packages published to GitHub Packages

Internal Package Registry​

Internal packages using the @space48-internal namespace are published to GitHub Packages. This ensures:

  • Private code remains private
  • Access control through GitHub permissions
  • Integration with our existing GitHub workflows

Registry Configuration​

Due to how NPM handles namespaces and registries, it's crucial to configure your .npmrc correctly. Each namespace should point to its respective registry:

@space48:registry=https://registry.npmjs.org/
@space48-internal:registry=https://npm.pkg.github.com/

⚠️ Important: Incorrect registry configuration can lead to package resolution issues. For example, if your .npmrc configures @space48 to use GitHub Packages, you won't be able to install public packages like @space48/foo from NPM, even if they exist there.

Best Practices​

  1. Choose the appropriate namespace:
    • Use @space48-internal/* for internal tooling and private packages
    • Use @space48/* for packages intended to be public (see Open Source NPM Publishing)
  2. Document any required .npmrc configuration in your package's README
  3. Always include comprehensive documentation
  4. Maintain a CHANGELOG.md
  5. Use semantic versioning
  6. Include proper TypeScript types when applicable
  7. Set appropriate package access levels (should be private for @space48-internal packages)

GitHub Packages Authentication​

When publishing to or installing from GitHub Packages, you'll need to authenticate. This can be done by:

  1. Creating a GitHub Personal Access Token with appropriate permissions
  2. Adding the token to your .npmrc: 
    //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

For CI/CD environments, use repository secrets for the authentication token.