The AAS WorldWide Telescope WebGL engine
Learn more about WWT here.
Developers’ quick start
- Check out this repository to a machine with Node.js and npm.
git submodule update --init
npx lerna bootstrap -- --legacy-peer-deps(You may be able to omit the arguments here, depending on your version of NPM. See this bug.)
- Either build or obtain the file
engine/wwtlib/bin/wwtlib.jsas described below.
npm run lint(uses ESLint)
npm run buildcreates:
- Commands to serve the web apps:
npm run serve-embedto serve the embed app
npm run serve-researchto serve the research app
npm run serve-creatorto serve the embed creator app
npm run test(mainly uses mocha and chai)
npm run doc(uses TypeDoc)
This repository is a monorepo containing the source for several interlocking TypeScript packages that together comprise the core of the WWT web framework. The most important subdirectories are:
engine/, the core engine code transpiled from C# and wrapped in TypeScript annotations
engine-vuex/, a higher-level package that turns the engine into a reusable Vue/Vuex component
embed/, a web application that turns WWT into a configurable, embeddable iframe
research-app/, an embeddable web application for astrophysics research using WWT.
- The narrative documentation in
README files inside the individual subdirectories give more information about their contents and development workflows.
There’s one big wrinkle to the build process: the bulk of the engine code is
actually C# code in the directory
engine/wwtlib/. It’s forked from
version of ScriptSharp, an unmaintained tool. Fortunately, that build process
results in a single file,
engine/wwtlib/bin/wwtlib.js, that you can download
from our CI systems if you’re not able to perform a Visual Studio build.
To build the engine library starting from C#:
- You need a Windows machine with Visual Studio 2017. Other versions of Visual Studio might also work.
- Open the
engine/WebGLEngine.slnsolution and build the project it contains. This should create the file
Otherwise, check out the latest continuous integration build of this repository,
scriptsharp artifact, and copy the
wwtlib.js file to the location
given above. (To find the artifact, go to the appropriate build in this project's
pipeline on Azure DevOps). Under 'Related', select '9 published', and download
scriptsharp). If you want to change the C# code, you can file a pull
request and access the artifacts associated with your pull request builds.
Building the rest of the code
Besides the creation of the file
everything in this repository is built using standard Node.js/npm tooling.
These tools must be installed before you can do anything else.
git submodule update --initto pull in needed Git submodules, namely the documentation theme in
npx lerna bootstrapto install all of the project dependencies and set up the necessary cross-links between individual packages in this repository.
Once setup is complete, the following commands will be useful:
npm run buildto build the subpackages
npm run lintto lint the subpackages (using eslint with TypeScript extensions)
npm run testto run the tests (mainly using mocha and chai)
npm run docto build most of the documentation (using TypeDoc) — but see below
Running these commands from inside package subdirectories unfortunately will
not work due to the centralized
node_modules directory we use with Lerna. To
lint command only for the
engine-types submodule, run:
npx lerna run --scope @wwtelescope/engine-types lint
--scope argument can be a glob expression if you want to run on a subset
Building the full documentation
Documentation is maintained in subdirectories of
docs/. The documentation is a
Frankenstein combination of the autogenerated API documentation and narrative
material written in CommonMark Markdown. The final HTML is assembled with the
static site generator Zola,
- Zola is fast and self-contained and ridiculously easy to install.
npm run doccommand will install the autogenerated documentation into
zola buildin a subdirectory of
docswill assembled the final HTML into
- The command
zola checkwill check the narrative docs for broken links.
- The command
zola servewill serve the documentation using a local server with autoreload.
Continuous Integration and Deployment
This repository uses Cranko to automate release workflows. This automation is essential to the smooth and reproducible deployment of the WWT web services.
Integration testing of the apps is done using Selenium, Nightwatch, and
BrowserStack. For the main branch, this is triggered automatically with each
commit/pull request. However, the test suite can also be run using a version of
the app on your local machine, either locally (using the Nightwatch binary) or
using BrowserStack (provided that you have a BrowserStack account). In either
case, you may need to modify the
point to the localhost port that you will be using (the default is
To run the test suite on a local version of the app with ChromeDriver:
npm run serve-research & # or equivalent cd tests npm install npm run build npm run local
To run tests on a local version of the app via BrowserStack's multi-browser, multi-platform infrastructure, do the following:
- Set the variables
BROWSERSTACK_ACCESS_KEYto your BrowserStack username and access key, respectively. You can find these values in your BrowserStack Account Settings.
- Run the test suite as above but with the final command:
npm run bs-local
By default, both of these local options will run the tests in Chrome. You can
adjust the testing environments adding the
-e option, which can be
accomplished with syntax such as
npm run bs-local -- -e firefox,edge
We love it when people get involved in the WWT community! You can get started by participating in our user forum or by signing up for our low-traffic newsletter. If you would like to help make WWT better, our Contributor Hub aims to be your one-stop shop for information about how to contribute to the project, with the Contributors’ Guide being the first thing you should read. Here on GitHub we operate with a standard fork-and-pull model.
All participation in WWT communities is conditioned on your adherence to the WWT Code of Conduct, which basically says that you should not be a jerk.
The AAS WorldWide Telescope system is a .NET Foundation project. Work on WWT has been supported by the American Astronomical Society (AAS), the US National Science Foundation (grants 1550701, 1642446, and 2004840), the Gordon and Betty Moore Foundation, and Microsoft.