Introduction

This template scaffolds a ...

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 "@vode-app/create-spa" version

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

# set metadata in package.json

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>

nginx as a Static File Server

Location directives for serving the SPA and static files:

server {
    # ...

    # placeholder:
        # <VODE_APP_PATH: <VODE_APP_PATH>
        # <VODE_APP_SPA_PATH: <VODE_APP_SPA_PATH>
        # <DIST_PATH: <DIST_PATH>
    location <VODE_APP_PATH>/<VODE_APP_SPA_PATH> {
        root <DIST_PATH>;
        rewrite ^ /index.html break;
        gzip off;
        sub_filter '<base href="" />' '<base href="<VODE_APP_PATH>/" />';
        sub_filter_once on;
        add_header Cache-Control "no-store";
    }
    location <VODE_APP_PATH> {
        root <DIST_PATH>;
        rewrite ^<VODE_APP_PATH>/(.*)$ /$1 break;
        try_files $uri =404;
        add_header Cache-Control "no-store";
    }

    # ...
}

Copy dist/ to the server:

# placeholder:
    # <DIST_PATH: <DIST_PATH>
    # <STATIC_FILES_SERVER: <STATIC_FILES_SERVER>

ssh <STATIC_FILES_SERVER> "rm -Rf <DIST_PATH>/*"
scp -rp dist/* <STATIC_FILES_SERVER>:<DIST_PATH>
ssh <STATIC_FILES_SERVER> "find <DIST_PATH> -type d -exec chmod 755 {} +"
ssh <STATIC_FILES_SERVER> "find <DIST_PATH> -type f -exec chmod 644 {} +"

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:

@vode-app:registry=https://git.chimps.quest/api/packages/vode-app/npm/
//git.chimps.quest/api/packages/vode-app/npm/:_authToken=${VODE_APP_REGISTRY_AUTH_TOKEN}

or bunfig.toml:

[install.scopes]
"vode-app" = { url = "https://git.chimps.quest/api/packages/vode-app/npm/", token = "$VODE_APP_REGISTRY_AUTH_TOKEN" }

# git.chimps.quest/api/packages/vode-app/npm/
export VODE_APP_REGISTRY_AUTH_TOKEN=<AUTH_TOKEN>
# or
$env:VODE_APP_REGISTRY_AUTH_TOKEN = "<AUTH_TOKEN>"
npm publish

CI/CD Workflows

Build and Publish

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

Parameter	Type	Description
RUNNER_LABEL	Variable	The label of the runner to use for the workflow.
ACCESS_TOKEN	Secret	The authentication token for the package registry.

.github/workflows/build-publish.yml:

name: Build and Publish

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ${{ vars.RUNNER_LABEL }}
    steps:
      - uses: actions/checkout@v4

      - name: Install
        env:
          VODE_APP_REGISTRY_AUTH_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        run: npm ci

      - name: Build
        run: npm run build

      - name: Test
        run: npm run tests

      - name: Publish
        env:
          VODE_APP_REGISTRY_AUTH_TOKEN: ${{ secrets.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