Skip to content

Development Workflow Guide

This guide covers everything you need to know about building, testing, and viewing the Polaris FHIR Implementation Guide.

Quick Commands

# First time setup
npm run setup

# Build everything
npm run build

# View the docs locally
npm run server
# Then open http://localhost:8080

# Clean up build artifacts
npm run clean

# Check if your environment is ready
npm run check-env

The easiest way to get a consistent development environment is using the DevContainer. It has everything pre-installed.

Setup DevContainer

  1. Install Prerequisites:
  2. Docker Desktop
  3. VS Code

  4. Remote - Containers extension

  5. Open in DevContainer:

  6. Open the project in VS Code
  7. You'll see a popup: "Folder contains a Dev Container configuration"
  8. Click "Reopen in Container"

  9. Wait for it to build (first time takes ~5 minutes)

  10. That's it! Everything is pre-installed and ready to go.

What's in the DevContainer?

  • Node.js 18
  • Java 11 (for FHIR IG Publisher)
  • Python 3.10 (for MkDocs)
  • Ruby 3.0
  • All npm dependencies pre-installed
  • Git configured
  • Helpful VS Code extensions

Building the Implementation Guide

The Full Build Process

When you run npm run build, here's what happens:

  1. Preprocessing - Generates a combined spec document
  2. SUSHI - Converts your FSH files to FHIR JSON
  3. IG Publisher - Creates the full implementation guide
  4. File Operations - Organizes outputs for documentation
  5. MkDocs - Builds the documentation website
  6. Packaging - Creates downloadable artifacts

Build Outputs

After building, you'll find:

  • output/ - The FHIR IG Publisher output (the actual IG)
  • docs/fhir/ - Copy of the IG for the docs site
  • site/ - The MkDocs documentation site
  • fsh-generated/ - Raw SUSHI output
  • polaris-fhir-spec.zip - Everything bundled up

Common Build Issues

"Java not found"

# Check Java version
java -version
# Should be 11 or higher

# On Mac:
brew install openjdk@11

# On Ubuntu/Debian:
sudo apt-get install openjdk-11-jdk

# On Windows:
# Download from https://adoptium.net/

"SUSHI errors"

  • Check your FSH syntax
  • Look for typos in profile names
  • Ensure all aliases are defined
  • Run npm run sushi alone to see detailed errors

"IG Publisher failed"

  • Usually means validation errors
  • Check output/qa.html for details
  • Look for missing references or invalid examples

Updating Documentation

Where Things Live

docs/                    # MkDocs documentation
├── features/           # Feature-specific docs
│   └── [feature]/
│       ├── index.md
│       └── .nav.yml    # Navigation config
├── guides/             # How-to guides
├── contributing/       # This guide!
└── fhir/              # Generated IG (don't edit)

input/pagecontent/      # FHIR IG pages
├── index.md           # IG home page
├── profiles.md        # Profile documentation
└── downloads.md       # Download links

Adding a New Documentation Page

  1. For general docs (MkDocs): 

    # Create your page
echo "# My New Feature" > docs/features/my-feature/index.md

# Add navigation
echo "- My Feature: my-feature/" >> docs/features/.nav.yml

  2. For FHIR IG content: 

    # Create page content
echo "### My Profile Details" > input/pagecontent/StructureDefinition-polaris-myprofile-intro.md

Documentation Tips

  • Use Markdown headers (##, ###) for structure
  • Include code examples
  • Add links to related pages
  • Keep it concise but complete

Viewing Your Work

Local Development Server

# Start the server
npm run server

# Or use the convenience scripts:
./__server      # Mac/Linux
./__server.cmd  # Windows

Then open: http://localhost:8080

The server auto-reloads when you change files in docs/.

What You'll See

  • MkDocs Site: The main documentation at http://localhost:8080
  • FHIR IG: Available at http://localhost:8080/fhir/
  • Live Reload: Changes appear instantly (for MkDocs content)

Key pages in the FHIR IG:

  • /fhir/index.html - IG home page
  • /fhir/artifacts.html - All profiles, extensions, examples
  • /fhir/qa.html - Build errors and warnings
  • /fhir/StructureDefinition-polaris-[type].html - Individual profiles

Testing Your Changes

Quick Validation

# Just run SUSHI (fast)
npx sushi .

# Full build (slower but complete)
npm run build

What to Check

  1. Build Success: No errors in console
  2. QA Report: Check output/qa.html
  3. Examples Validate: All green in QA report
  4. Links Work: Click around the generated site
  5. Narratives Render: Check the human-readable text

Pre-PR Checklist

  • [ ] npm run build completes without errors
  • [ ] No new errors in output/qa.html
  • [ ] Examples validate against profiles
  • [ ] Documentation renders correctly
  • [ ] Links aren't broken

Convenience Scripts

We have helper scripts for cross-platform compatibility:

# Mac/Linux versions
./__build      # Full build
./__clean      # Clean artifacts
./__server     # Start dev server

# Windows versions
./__build.cmd
./__clean.cmd
./__server.cmd

These handle platform differences automatically.

Advanced Workflows

Building Just SUSHI

npx sushi .

Fast way to check FSH syntax without full IG build.

Building Just the IG

cd output
./_genonce.sh  # Mac/Linux
./_genonce.bat # Windows

Skips SUSHI if you just changed narratives or pages.

Custom IG Publisher Settings

Edit ig.ini for publisher settings: - ig - IG resource file name - template - Template to use - usage-stats-opt-out - Privacy setting

Debugging Build Issues

  1. Enable verbose output: 

    npm run build -- --verbose

  2. Check intermediate files:

  3. fsh-generated/ - SUSHI output

  4. output/temp/ - IG Publisher work files

  5. Run steps individually: 

    npx sushi .
cd output && ./_genonce.sh
cd .. && npm run mkdocs:build

Environment Variables

Proxy Settings

If behind a corporate proxy:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

Java Memory

For large IGs:

export JAVA_OPTS="-Xmx4g"

Publisher Settings

export FHIR_PUBLISHER_OPTS="-debug"

Tips and Tricks

Speed Up Builds

  1. Use DevContainer - No setup time
  2. Incremental builds - Only build what changed
  3. Skip packaging - Comment out zip creation during development
  4. Local IG Publisher - Download once, reuse

Watch for Changes

While we don't have automatic FSH watching, you can:

  1. Use VS Code's "Run on Save" extension
  2. Create a simple watch script
  3. Use the dev server for docs (auto-reloads)

Profile Development Flow

  1. Write FSH profile
  2. Run npx sushi . (quick syntax check)
  3. Create JSON example
  4. Run full build
  5. Check QA report
  6. View in browser
  7. Iterate

Common Keyboard Shortcuts

In VS Code with DevContainer:

  • Ctrl+Shift+B - Run build task
  • Ctrl+`` - Open terminal
  • Ctrl+Shift+P - Command palette

Getting Help

Build Not Working?

  1. Run npm run check-env
  2. Check error messages carefully
  3. Look at output/qa.html
  4. Ask Shawn (shawn.vincent@well.company)

Can't Get DevContainer Working?

  • Make sure Docker is running
  • Check VS Code extensions
  • Try "Rebuild Container"
  • Fall back to local setup if needed

Something Else?

Create an issue or reach out directly. We're here to help!

Pro tip: The DevContainer is really the way to go. It just works™️