# Ephemeris packages on npm

The npm packages that compute planetary positions, compared by licence, latest release, where they run and what they compute, with a snippet that runs.

Engine 1.0.0: On npm.
Archive identity and release status: https://zodiacs.org/developers/engine/

## Positions in a few lines

positions(date) returns the Sun, the Moon, eight planets and the true lunar nodes: each one's apparent geocentric longitude of date in degrees, its sign and its daily speed. It runs in Node, Deno, Bun, browsers and Workers and makes no network request.

~~~javascript
import { positions } from '@zodiacs/engine';
for (const { body, lon, sign, retrograde } of positions('2026-10-12T00:00:00Z')) {
  console.log(body.padEnd(10), lon.toFixed(4), sign, retrograde ? 'retrograde' : '');
}
~~~

## The packages

As the npm registry listed them on 13 October 2026:

@zodiacs/engine 1.0.0, of 11 October 2026, MIT AND CC-BY-4.0: positions, charts with thirteen house systems, aspects, events, returns and a sidereal zodiac, in JavaScript.

astronomy-engine 2.1.19, of December 2023, MIT: astronomical positions, rise and set times and phases, in JavaScript; @zodiacs/engine is built on it.

ephemeris 3.2.1, of August 2026, GPL-3.0: a JavaScript port of Moshier's analytic ephemeris, which can use Swiss Ephemeris through sweph instead.

sweph 2.10.3-8, of August 2026, AGPL-3.0-or-later or LGPL-3.0-or-later: a native Node binding of Swiss Ephemeris 2.10.03.

swisseph 0.5.17, of January 2022, with no licence declared on npm: a native Node binding of an earlier Swiss Ephemeris.

## Choosing

A chart needs more than positions: the angles and houses need a place and an exact instant, and a birth time needs its time zone at the date. The GPL and AGPL packages carry their licence terms into what you distribute, and the AGPL into a service others use over a network.

## Install the release

~~~sh
npm install @zodiacs/engine@1.0.0
~~~

npm's 1.0.0 tarball is byte-identical to the archive the engine repository carries. To install those bytes from the carrier, with their digest checked before npm sees them, run this in the project's directory instead:

~~~sh
( set -eu
# POSIX shell — macOS, Linux or WSL. Not PowerShell. It runs in a subshell, so
# a failure stops the install without closing your terminal.
BASE=$(pwd)
FILE='zodiacs-engine-1.0.0.tgz'
# Run it in your project's directory. Without a package.json here, npm would
# install into the nearest parent directory that has one.
if test ! -f package.json; then
  echo "Stop: there is no package.json here. Run this in your project's directory, or create one first with: npm init -y" >&2
  exit 1
fi
if test -e "$FILE" || test -L "$FILE"; then
  echo "Stop: $FILE already exists here. Move or delete it, then run this again." >&2
  exit 1
fi
# A download that fails verification is removed, so the guard above does not
# then block the retry. Once npm takes over the archive stays: npm reports its
# own failures, and the file is what you would retry with.
trap 'status=$?; if test "$status" -ne 0; then rm -f "$BASE/$FILE"; fi; exit $status' EXIT

curl --disable --fail --silent --show-error --location --proto '=https' --max-time 120 \
  'https://raw.githubusercontent.com/zodiacs-org/engine/38d31854e5716454921b6ce8a211788a0984328e/artifacts/zodiacs-engine-1.0.0.tgz' -o "$FILE"

node --input-type=module <<'JS'
import { readFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
const file = 'zodiacs-engine-1.0.0.tgz';
const expected = 'c4d3754de899fb98882331e6d7b9ce3ce77fb2072baeb002aa0ef8c77b0ab0f6';
const bytes = readFileSync(file);
const actual = createHash('sha256').update(bytes).digest('hex');
if (actual !== expected) {
  console.error(`Stop: this is not the published archive.\n  expected ${expected}\n  got      ${actual}`);
  console.error('Nothing was installed.');
  process.exit(1);
}
console.log(`Archive verified: ${actual}`);
JS

trap - EXIT
npm install --ignore-scripts "./$FILE"
echo "Installed @zodiacs/engine@1.0.0 from the verified archive."
)
~~~

## References

- [Node quickstart](https://zodiacs.org/developers/docs/node/)
- [Engine validation](https://zodiacs.org/developers/engine/)
- [astronomy-engine on npm](https://www.npmjs.com/package/astronomy-engine)
- [ephemeris on npm](https://www.npmjs.com/package/ephemeris)
- [sweph on npm](https://www.npmjs.com/package/sweph)
- [swisseph on npm](https://www.npmjs.com/package/swisseph)