Introduction

This template scaffolds a package that is itself a template for other packages.

Table of Contents

1. Quick Start
2. Documentation
3. DevOps
   1. Change Management
   2. Registry
   3. CI/CD Workflows

Quick Start

# print the latest version
npm info "@temir.ra/create-template" version

# create/update a package from the template in the current directory
npm create --no-install --no-git "@temir.ra/template@latest" .

# set metadata in package.json
# update <BINARY_NAME> in package.json#bin

npm update

Documentation

The following sections explain the configurations and conventions baked into the generated package. Useful when adapting it to fit specific needs.

<DOCUMENTATION>

DevOps

npm install
npm update

npm run clean
npm run build
npm run tests

npx tsx dist/cli.bundle.js -- example/

git fetch upstream
git fetch origin
git fetch . upstream/main:origin/main
git fetch . origin/main:main
git push origin main
git merge --ff-only main
git push

Change Management

1. Create a new branch for the change.
2. Make the changes and commit.
3. Bump the version in package.json.
4. Add an entry for the new version in CHANGELOG.md.
5. Pull-request the branch.
6. Ensure package artifacts are current.
7. Publish.

Registry

.npmrc:

@temir.ra:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPMJSORG_REGISTRY_AUTH_TOKEN}

or bunfig.toml:

[install.scopes]
"temir.ra" = { url = "https://registry.npmjs.org/", token = "$NPMJSORG_REGISTRY_AUTH_TOKEN" }

# registry.npmjs.org/
export NPMJSORG_REGISTRY_AUTH_TOKEN=<AUTH_TOKEN>
# or
$env:NPMJSORG_REGISTRY_AUTH_TOKEN = "<AUTH_TOKEN>"
npm publish

CI/CD Workflows

NPM Build and Publish

⚠️ .npmrc configuring the package registry and its authentication token is required for the workflow to work.

|Parameter|Type|Description| |-----|-----|-----| |NPM_RUNNER_LABEL|Variable|The label of the runner to use for the workflow.| |NPM_ACCESS_TOKEN|Secret|The authentication token for the package registry.|

.github/workflows/npm-build-publish.yml:

name: NPM Build and Publish

on:
  push:
    branches:
      - main
    # paths:
    #   - <SERVICE_PATH><SERVICE_KEY>/**
    #   - .github/workflows/<SERVICE_KEY>-npm-build-publish.yml

jobs:
  publish:
    name: NPM Build and Publish
    runs-on: ${{ vars.NPM_RUNNER_LABEL }}
    # defaults:
    #   run:
    #     working-directory: <SERVICE_PATH><SERVICE_KEY>/
    steps:
      - uses: actions/checkout@v4
        name: Checkout

      - name: Install
        env:
          NPMJSORG_REGISTRY_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
        run: npm ci

      - name: Build
        run: npm run build

      - name: Test
        run: npm run tests

      - name: Publish
        env:
          NPMJSORG_REGISTRY_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
        run: |
          PKG_NAME=$(node -p "require('./package.json').name")
          PKG_VERSION=$(node -p "require('./package.json').version")
          NPM_TAG="latest"
          if echo "$PKG_VERSION" | grep -q -- '-'; then
            NPM_TAG="next"
          fi
          if npm view "$PKG_NAME@$PKG_VERSION" version >/dev/null 2>&1; then
            echo "$PKG_NAME@$PKG_VERSION already published, skipping."
          else
            npm publish --tag "$NPM_TAG"
          fi