SUSHI (FSH Compiler)

3.19.0 verified Fri May 01 auth: no javascript

SUSHI (SUSHI Unshortens Short Hand Inputs) is a reference implementation compiler for FHIR Shorthand (FSH), a domain-specific language for defining FHIR Implementation Guides. Current stable version is 3.19.0, released with monthly cadence. Key differentiators: first-class support for FHIR R4/R4B/R5, dependency aliasing (since v3.16.0), multiline strings in invariants and mapping comments (v3.18.0), and integration with IG Publisher. Primarily used via CLI (`sushi build`). Ships TypeScript types.

Common errors

error Error: Could not find package 'hl7.fhir.us.core#6.1.0' ↓

cause SUSHI cannot resolve a FHIR package dependency, possibly due to network issues or missing registry.

fix

Check internet connection and ensure the package exists. Use sushi update-dependencies to refresh.

error TypeError: Cannot read properties of undefined (reading 'profile') ↓

cause Attempting to access a profile that was not defined or loaded correctly.

fix

Ensure the FSH file contains a valid Profile statement and that all dependent profiles are resolved.

error ERROR: SUSHI requires Node.js version >=18. Current version: 14.15.0 ↓

cause Node.js version is too old.

fix

Install Node.js v18 or later. Recommended: v22.

Warnings

gotcha SUSHI requires Node.js >=18, but Node 22 is strongly recommended. Older versions may experience dependency resolution issues. ↓

fix Upgrade Node.js to version 22.

breaking Dependency aliasing syntax introduced in v3.16.0: alias@npm:packageId. Projects with duplicate package names must update their sushi-config.yaml. ↓

fix Add alias prefix for duplicate dependency entries.

deprecated The _updatePublisher and _genonce scripts are replaced by _build in sushi init since v3.19.0. ↓

fix Use `sushi init` to generate _build script.

gotcha Multiline strings in invariants are only supported since v3.18.0. Older versions will fail to parse FSH with multiline invariant expressions. ↓

fix Upgrade to v3.18.0 or later.

Install

npm install fsh-sushi

yarn add fsh-sushi

pnpm add fsh-sushi

Imports

sushi
wrong
```
const sushi = require('fsh-sushi')
```
correct
```
import sushi from 'fsh-sushi'
```
ESM-only since v3; CLI usage does not require imports.

build

wrong

import build from 'fsh-sushi'

correct

import { build } from 'fsh-sushi'

Named export for programmatic API.

FSHToFHIR

wrong

import FSHToFHIR from 'fsh-sushi'

correct

import { FSHToFHIR } from 'fsh-sushi'

TypeScript types available; use named import.

Quickstart

Demonstrates programmatic use of SUSHI compiler via ESM import, building a project from the command-line argument.

#!/usr/bin/env node
import sushi from 'fsh-sushi';
import path from 'path';
const projectPath = process.argv[2] || '.';
try {
  const result = await sushi.build(projectPath, { logLevel: 'info' });
  console.log('Build succeeded:', result);
} catch (err) {
  console.error('Build failed:', err.message);
}