Skip to content

NPM #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jrcain-usgs wants to merge 3 commits into
base: main
Choose a base branch
from
Open

NPM #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
088b86c
npm package
jrcain-usgs Jul 28, 2026
2e28d4d
NPM Readme Update
jrcain-usgs Jul 30, 2026
7f4fa4f
NPM Publish CICD
jrcain-usgs Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/release_wasm.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ on:

permissions:
contents: write # required to upload release assets
id-token: write # Required for OIDC trusted publishing

jobs:
build-and-upload:
Expand Down Expand Up @@ -103,3 +104,15 @@ jobs:
run: |
gh release upload "${{ steps.package.outputs.tag }}" \
"${{ steps.package.outputs.asset }}" --clobber

- uses: actions/setup-node@v6
with:
node-version: '24'
registry-url: 'https://registry.npmjs.org'
package-manager-cache: false

- name: Publish to NPM
run: |
npm install -g npm@latest # ensure OIDC-capable npm (>= 11.5.1)
npm install
npm publish
Comment on lines 16 to +118

@Kelvinrr Kelvinrr Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it possible for this to be ran manually? Therefore, it could overwrite the existing build? Maybe we only want it to run on release?

1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
.DS_Store
build/
build-wasm/
dist/
node_modules/
cmake_test_discovery_*.json
test_pyspiceql*
48 changes: 37 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,32 @@ The SpiceQL API is available via Python bindings in the module `pyspiceql`. The

## WebAssembly / JavaScript

SpiceQL can be compiled to WebAssembly with [Emscripten](https://emscripten.org/), exposing the `api.h` surface to JavaScript so it runs in the browser or Node. This is a separate build from the native library and its Python bindings.
### Setup/Installation Options

#### [GitHub Releases (Manual Download) ↗](https://github.com/DOI-USGS/SpiceQL/releases)

#### NPM Installation

```sh
# In your terminal in your project directory:
npm install @usgs-astrogeology/spiceql
```

```js
// In your javascript:
import { loadSpiceQL } from '@usgs-astrogeology/spiceql'
```

*A Module Bundler, like Vite, is required for this kind of import.*


#### Import from CDN (jsDelivr)

```js
// In your javascript:
import { loadSpiceQL } from 'https://cdn.jsdelivr.net/npm/@usgs-astrogeology/spiceql/dist/spiceql.js';
```

> **NOTE**: There is no CDN/npm package yet. You must either build the module locally or download the prebuilt artifact from the [GitHub Releases](https://github.com/DOI-USGS/SpiceQL/releases) page.

### Building locally

Expand All @@ -100,8 +123,9 @@ emcmake cmake -S . -B build-wasm \

cmake --build build-wasm -j"$(getconf _NPROCESSORS_ONLN)"
```
*If you get a permission denied error, use a lower number of cores in the last command: `-j4` or `-j1` instead of `-j"$(getconf _NPROCESSORS_ONLN)"`*

The CMake options are:
#### CMake Options:

| Option | Value | Why |
| --- | --- | --- |
Expand All @@ -126,6 +150,7 @@ Copy the three `spiceql_wasm.*` artifacts and both wrappers (`bindings/wasm/spic

```js
// example.mjs — run with: node example.mjs

import { loadSpiceQL } from './spiceql.js';

const spiceql = await loadSpiceQL();
Expand All @@ -144,31 +169,32 @@ console.log(result); // ET seconds past J2000
console.log(kernels); // { lsk: ['/kernels/naif0012.tls'] }
```

In a browser it works the same way — `import` `spiceql.js` locally from a
In a browser it works the same way — `import` `spiceql.js` in a
`<script type="module">` and use `fetch()` to get kernel bytes for `mountKernel`.
The five files (`spiceql.js`, `naifspice.js`, `spiceql_wasm.js`,
`spiceql_wasm.wasm`, `spiceql_wasm.data`) and your kernels just need to be
served over HTTP from the same folder (any static host works; opening the page from `file://` does not,
because the browser blocks `fetch()` of local files):
because the browser blocks `fetch()`):

```html
<!doctype html>
<!-- index.html — served next to spiceql.js and the spiceql_wasm.* files -->
<script type="module">
import { loadSpiceQL } from './spiceql.js';
import { loadSpiceQL } from 'https://cdn.jsdelivr.net/npm/@usgs-astrogeology/spiceql/dist/spiceql.js';

const spiceql = await loadSpiceQL();

// No kernel search in WASM — fetch your own kernel and write it into the
// No kernel search in WASM — fetch the kernel and write it into the
// virtual filesystem before calling.
const bytes = new Uint8Array(await (await fetch('naif0012.tls')).arrayBuffer());
const bytes = new Uint8Array(await (await fetch('https://cdn.jsdelivr.net/gh/DOI-USGS/SpiceQL/SpiceQL/db/kernels/naif0012.tls')).arrayBuffer());
spiceql.mountKernel('/kernels/naif0012.tls', bytes);

const { result } = spiceql.utcToEt('2000-01-01T00:00:00', {
const { result, kernels } = spiceql.utcToEt('2000-01-01T00:00:00', {

@Kelvinrr Kelvinrr Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might not be the best example in hindsight, UTC2et doesn't need an LSK in SpiceQL. But we can leave as is and make an issue about changing this example.

searchKernels: false,
kernelList: ['/kernels/naif0012.tls'],
});
document.body.textContent = `ET = ${result}`; // ET seconds past J2000

console.log(result); // ET seconds past J2000
console.log(kernels); // { lsk: ['/kernels/naif0012.tls'] }
</script>
```

Expand Down
39 changes: 35 additions & 4 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
{
"name": "spiceql-wasm",
"name": "@usgs-astrogeology/spiceql",
"version": "1.7.0",
"description": "WebAssembly/JS bindings for SpiceQL (Emscripten). See bindings/wasm.",
"type": "module",
"private": true,
"exports": {
".": "./bindings/wasm/spiceql.js"
".": "./dist/spiceql.js"
},
"files": [
"bindings/wasm/spiceql.js"
"dist/spiceql.js",
"dist/naifspice.js",
"dist/spiceql_wasm.data",
"dist/spiceql_wasm.js",
"dist/spiceql_wasm.wasm",
"README.md",
"LICENSE.md"
],
"scripts": {
"prepack": "rm -rf dist && mkdir -p dist && cp bindings/wasm/spiceql.js bindings/wasm/naifspice.js build-wasm/bindings/wasm/spiceql_wasm.js build-wasm/bindings/wasm/spiceql_wasm.data build-wasm/bindings/wasm/spiceql_wasm.wasm dist/",
"test": "node --test \"bindings/wasm/tests/*.test.mjs\""
},
"engines": {
Expand All @@ -20,5 +26,30 @@
"repository": {
"type": "git",
"url": "https://github.com/DOI-USGS/SpiceQL.git"
},
"homepage": "https://github.com/DOI-USGS/SpiceQL#readme",
"bugs": {
"url": "https://github.com/DOI-USGS/SpiceQL/issues"
},
"keywords": [
"spice-query-language",
"spiceql",
"planetary",
"webassembly",
"wasm",
"astrogeology",
"kernels",
"remote-sensing",
"mars",
"moon",
"planetary-science",
"spice-kernels",
"spice",
"naif",
"naif-spice"
],
"author": "USGS Astrogeology Science Center",
"publishConfig": {
"access": "public"
}
}
Loading