Skip to main content

Publishing to NPM

At Space 48, we prioritise publishing our open source packages to NPM under the @space48 namespace. This ensures our public packages are easily accessible to the wider community.

Package Namespace​

All our public packages use the @space48/* namespace on NPM. For internal packages and tooling, see our internal package management documentation.

CI/CD Configuration​

We have set up automated publishing to NPM through our CI/CD pipelines. A dedicated service user space48-ci has been created in our NPM account to handle automated publishing. The full credentials for this service account are stored securely in our password management system.

Available Secrets​

The following secrets have been configured in both GitHub and BitBucket environments for NPM publishing:

  • NPM_USERNAME: The username for the CI service account
  • NPM_TOKEN: Authentication token for NPM publishing

Using in CI/CD Pipelines​

These secrets can be utilised in your CI/CD pipelines (GitHub Actions or BitBucket Pipelines) to authenticate and publish packages to NPM.

Example GitHub Action​

name: Publish to NPM
on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "20.x"
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm run build # if you have a build step
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Example BitBucket Pipeline​

pipelines:
  tags:
    "*":
      - step:
          name: Publish to NPM
          script:
            - npm ci
            - npm run build # if you have a build step
            - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
            - npm publish

Best Practices​

  1. Always include a comprehensive README.md
  2. Maintain a CHANGELOG.md
  3. Use semantic versioning
  4. Include proper TypeScript types when applicable
  5. Set up appropriate NPM package access levels (public/private)
  6. Use the correct namespace for your package:
    • @space48/* for public packages on NPM
    • @space48-internal/* for internal packages on GitHub Packages
  7. Document any required .npmrc configuration in your package's README

TODO: Add more specific guidelines and best practices for NPM package management.