solar-spa

NREL Solar Position Algorithm compiled to WebAssembly. Calculates solar zenith, azimuth, incidence angle, sunrise, sunset, solar noon, and equation of time for any location and date.

The algorithm is the NREL SPA by Ibrahim Reda and Afshin Andreas, originally written in C. This package compiles the original C source to WASM via Emscripten and provides a TypeScript/JavaScript interface on top.

Installation

npm install solar-spa

Quick Start

import { spa } from 'solar-spa';

const result = await spa(
  new Date(2025, 5, 21, 12, 0, 0),   // June 21, 2025 at noon
  40.7128,                             // latitude (NYC)
  -74.0060,                            // longitude
  { timezone: -4, elevation: 10 }      // EDT (UTC-4), 10m elevation
);

console.log(result.zenith);       // ~27   (degrees from vertical)
console.log(result.azimuth);      // ~179  (degrees from north)
console.log(result.sunrise);      // ~5.4  (fractional hours)
console.log(result.sunset);       // ~20.5 (fractional hours)

CommonJS works too:

const { spa } = require('solar-spa');

API

spa(date, latitude, longitude, options?)

Returns a Promise<SpaResult> with raw numeric values.

Parameters:

| Name | Type | Description | | --- | --- | --- | | date | Date | Date and time for the calculation | | latitude | number | Observer latitude, -90 to 90 (negative = south) | | longitude | number | Observer longitude, -180 to 180 (negative = west) | | options | object | Optional. See below |

Options:

| Option | Type | Default | Description | | --- | --- | --- | --- | | timezone | number | auto | Hours from UTC. Auto-detected from the Date object if omitted | | elevation | number | 0 | Meters above sea level | | pressure | number | 1013.25 | Atmospheric pressure in millibars | | temperature | number | 15 | Temperature in Celsius | | delta_ut1 | number | 0 | UT1-UTC correction in seconds | | delta_t | number | 67 | TT-UTC difference in seconds | | slope | number | 0 | Surface slope in degrees | | azm_rotation | number | 0 | Surface azimuth rotation in degrees | | atmos_refract | number | 0.5667 | Atmospheric refraction in degrees | | function | number | 3 | SPA function code (see below) |

Result fields:

| Field | Unit | Description | | --- | --- | --- | | zenith | degrees | Topocentric zenith angle | | azimuth | degrees | Topocentric azimuth, eastward from north | | azimuth_astro | degrees | Topocentric azimuth, westward from south | | incidence | degrees | Surface incidence angle | | sunrise | fractional hours | Local sunrise time | | sunset | fractional hours | Local sunset time | | suntransit | fractional hours | Solar noon | | sun_transit_alt | degrees | Sun transit altitude | | eot | minutes | Equation of time | | error_code | integer | 0 on success |

spaFormatted(date, latitude, longitude, options?)

Same as spa(), but sunrise, sunset, and suntransit are returned as HH:MM:SS strings. Returns "N/A" for these fields during polar day or polar night.

formatTime(hours)

Converts fractional hours to an HH:MM:SS string. Returns "N/A" for non-finite or negative values (polar night/day scenarios).

init()

Pre-initializes the WASM module. Optional. The module initializes automatically on the first spa() call. Useful if you want to pay the initialization cost at application startup rather than on the first calculation.

Function Codes

| Constant | Value | Computes | | --- | --- | --- | | SPA_ZA | 0 | Zenith and azimuth | | SPA_ZA_INC | 1 | Zenith, azimuth, and incidence | | SPA_ZA_RTS | 2 | Zenith, azimuth, and rise/transit/set | | SPA_ALL | 3 | All output values |

Architecture

The package has three layers:

1. C layer (src/spa.c, src/spa_wrapper.c): The original NREL SPA algorithm with a thin wrapper that exposes a flat function signature suitable for WASM.

2. WASM layer (wasm/spa-module.js): Compiled with Emscripten using -sSINGLE_FILE=1, which inlines the WASM binary as base64. No external .wasm file to resolve. This eliminates the bundler path-resolution issues that plague most WASM packages.

3. TypeScript layer (src/index.ts, src/types.ts): Written in TypeScript and compiled by tsup to both CJS and native ESM with generated declaration files. Singleton WASM initialization, cached cwrap bindings, input validation, and named struct offset constants.

Build Flags

The WASM binary is compiled with:

• -O3 -flto: Maximum optimization with link-time optimization
• -sSINGLE_FILE=1: WASM inlined as base64 (no file path resolution)
• -sMODULARIZE=1: No global Module pollution
• -sNO_FILESYSTEM=1: No filesystem API bundled (saves ~15KB)
• -sINITIAL_MEMORY=1048576: 1MB fixed memory (SPA needs very little)
• -sASSERTIONS=0: No debug assertions in production
• -sENVIRONMENT='node,web,worker': Works in Node.js, browsers, and web workers

Compatibility

Tested in:

• Node.js 20+
• Modern browsers (Chrome, Firefox, Safari, Edge)
• Webpack 5
• Vite
• Next.js (both Pages and App Router)
• Web Workers

The SINGLE_FILE approach eliminates the .wasm file resolution problem that breaks most WASM packages in bundlers. There is no external binary to locate at runtime.

TypeScript

Full type definitions are generated from the TypeScript source and included with the package. Import types directly:

import { spa, SPA_ALL } from 'solar-spa';
import type { SpaResult, SpaOptions } from 'solar-spa';

Documentation

See the Wiki for detailed documentation: API reference, architecture, performance, bundler compatibility, validation benchmarks, and more.

Related

• nrel-spa: Pure JavaScript port of the same algorithm. No WASM dependency, synchronous API. Better choice if you do not need WASM-level performance.
• NREL SPA: The original algorithm specification and C source.
• pray-calc: Islamic prayer time calculator built on nrel-spa.

Acknowledgments

This package includes the Solar Position Algorithm (SPA) developed at the National Renewable Energy Laboratory (NREL) by Ibrahim Reda and Afshin Andreas. The C source files spa.c and spa.h are copyright Alliance for Sustainable Energy, LLC (2008-2011) and are distributed under the terms included in those files.

Reda, I., Andreas, A. (2004). "Solar Position Algorithm for Solar Radiation Applications." Solar Energy, 76(5), 577-589. doi:10.1016/j.solener.2003.12.003

The original C source and an online calculator are available at midcdmz.nrel.gov/spa.

License

MIT (wrapper, TypeScript source, and build tooling). The NREL SPA C source (src/spa.c, src/spa.h) is subject to its own terms; see the notice in those files.