GITHUB_PACKAGES_GUIDE.md

GitHub Packages for FHIR Implementation Guide

What is GitHub Packages?

GitHub Packages is a software package hosting service that allows you to host your software packages privately or publicly and use them as dependencies in your projects. It provides:

• Unified Platform: Source code and packages in one place
• Integrated Permissions: Uses GitHub's existing access controls
• Multiple Registries: Supports npm, Docker, Maven, NuGet, RubyGems
• Free for Public Repos: Unlimited bandwidth and storage for public packages

Current Status

Your Repository: Currently has NO packages published
URL: https://github.com/ClinyQAi/open-nursing-core-ig/packages

Why Publish Your FHIR IG as a Package?

1. Standard FHIR Distribution Method

FHIR Implementation Guides are commonly distributed as npm packages. This allows:

• Other developers to install your IG as a dependency: npm install @cliniqai/open-nursing-core-ig
• Automated dependency management and versioning
• Integration with FHIR tooling (SUSHI, IG Publisher, validators)

2. Benefits for Your Project

For Developers:

• Easy installation: npm install @cliniqai/open-nursing-core-ig
• Version management: Pin to specific versions
• Dependency resolution: Automatically pull required dependencies

For Healthcare Organizations:

• Simplified deployment of your nursing profiles
• Consistent versioning across environments
• Integration with existing FHIR servers (HAPI, Firely, etc.)

For the FHIR Community:

• Discoverable on npm registry
• Reusable profiles and extensions
• Contributes to NHS/UK FHIR ecosystem

3. What You Can Publish

Based on your repository structure:

Package Type	What to Publish	Use Case
npm	FHIR IG package (profiles, extensions, valuesets)	Primary distribution method
Docker	Containerized IG website + HAPI FHIR server	Easy deployment
npm	Validation tools (if you create custom validators)	Developer tooling

How to Publish Your FHIR IG as an npm Package

Step 1: Create package.json in Root Directory

{
  \"name\": \"@cliniqai/open-nursing-core-ig\",
  \"version\": \"0.1.0\",
  \"description\": \"Open Nursing Core FHIR Implementation Guide - UK Core compliant nursing profiles\",
  \"main\": \"package/package.json\",
  \"files\": [
    \"docs/package.tgz\",
    \"docs/package/**\",
    \"input/**\",
    \"fsh-generated/**\"
  ],
  \"keywords\": [
    \"fhir\",
    \"nursing\",
    \"uk-core\",
    \"nhs\",
    \"implementation-guide\",
    \"hl7\"
  ],
  \"author\": \"ClinyQAi\",
  \"license\": \"Apache-2.0\",
  \"repository\": {
    \"type\": \"git\",
    \"url\": \"https://github.com/ClinyQAi/open-nursing-core-ig.git\"
  },
  \"publishConfig\": {
    \"registry\": \"https://npm.pkg.github.com\"
  },
  \"fhir\": {
    \"canonical\": \"https://fhir.clinyq.ai\",
    \"version\": \"4.0.1\"
  }
}

Step 2: Authenticate with GitHub Packages

Create a Personal Access Token:

1. Go to: https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scopes: write:packages, read:packages
4. Copy the token

Configure npm:

# Create/edit ~/.npmrc
echo \"//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE\" >> ~/.npmrc
echo \"@cliniqai:registry=https://npm.pkg.github.com\" >> ~/.npmrc

Step 3: Build Your IG

# Run the FHIR IG Publisher
./_genonce.sh  # or _genonce.bat on Windows

# This generates:
# - docs/package.tgz (the npm package)
# - docs/package/ directory with FHIR resources

Step 4: Publish to GitHub Packages

# From repository root
npm publish

Step 5: Automate with GitHub Actions

Create .github/workflows/publish-package.yml:

name: Publish FHIR IG Package

on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@cliniqai'
      
      - name: Build FHIR IG
        run: |
          ./_genonce.sh
      
      - name: Publish to GitHub Packages
        run: npm publish
        env:
          NODE_AUTH_TOKEN: \${{ secrets.GITHUB_TOKEN }}

How Others Would Use Your Package

Install the Package

# Configure npm to use GitHub Packages
echo \"@cliniqai:registry=https://npm.pkg.github.com\" >> .npmrc

# Install your IG
npm install @cliniqai/open-nursing-core-ig

Use in FHIR Projects

// In a FHIR validator or server
const igPackage = require('@cliniqai/open-nursing-core-ig');

// Access profiles
const newsProfile = igPackage.profiles['ONCore-NEWS2-Observation'];

// Use in HAPI FHIR
// Add as dependency in pom.xml or package.json

Alternative: Publish to Official FHIR Registry

You can also publish to the official FHIR package registry:

1. Register at: https://registry.fhir.org
2. Submit your IG: After building, submit docs/package.tgz
3. Benefits:
   • Listed on official FHIR registry
   • Discoverable by all FHIR tools
   • Part of the global FHIR ecosystem

Docker Container Publishing

You can also publish a Docker container with your IG:

# Dockerfile for IG website
FROM nginx:alpine
COPY docs/ /usr/share/nginx/html/
EXPOSE 80
CMD [\"nginx\", \"-g\", \"daemon off;\"]

Build and publish:

# Build
docker build -t ghcr.io/cliniqai/open-nursing-core-ig:latest .

# Login to GitHub Container Registry
echo \$GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Push
docker push ghcr.io/cliniqai/open-nursing-core-ig:latest

Recommended Next Steps

1. ✅ Create package.json in repository root (see template above)
2. ✅ Build your IG to generate docs/package.tgz
3. ✅ Test locally before publishing
4. ✅ Publish first version manually to verify
5. ✅ Set up GitHub Actions for automated publishing on releases
6. ✅ Document installation in your README.md

Benefits Summary

Benefit	Description
Discoverability	Listed on GitHub and npm registries
Version Control	Semantic versioning (0.1.0, 0.2.0, 1.0.0)
Dependency Management	Automatic updates and compatibility
Professional Distribution	Standard method used by HL7 and NHS Digital
CI/CD Integration	Automated builds and releases
Community Adoption	Easier for others to use your profiles

Example: How NHS Digital Does It

NHS Digital publishes their FHIR packages:

• UK Core: uk.nhsdigital.r4
• Care Connect: uk.nhsconnect.r4

Your package would be:

• Package Name: @cliniqai/open-nursing-core-ig
• Canonical URL: https://fhir.clinyq.ai
• Version: Following semantic versioning

Questions?

• Cost: Free for public repositories
• Storage: Unlimited for public packages
• Bandwidth: Unlimited for public packages
• Private Packages: Included in GitHub Pro/Team plans

---

Ready to publish? Start with Step 1 above and create your package.json file!