Contributing to deck.gl

Thanks for taking the time to contribute!

PRs and bug reports are welcome, and we are actively looking for new maintainers.

Setting Up Dev Environment

The master branch is the active development branch.

Building deck.gl locally from the source requires node.js >=14. Further limitations on the Node version may be imposed by puppeteer and headless-gl. We use yarn to manage the dependencies of deck.gl, and volta to manage the Node and yarn version.

git checkout master
yarn bootstrap
yarn test

See additional instructions for Windows, Linux and Apple M1.

Run the website:

yarn build
cd website
yarn
yarn start

Run the layer browser application:

cd examples/layer-browser
yarn
yarn start-local

If you consider opening a PR, here is some documentation to get you started:

vis.gl developer process
deck.gl API design guidelines

Testing examples with modified deck.gl source

Each example can be run so that it is built against the deck.gl source code in this repo instead of building against the installed version of deck.gl. This enables using the examples to debug the main deck.gl library source.

To do so use the yarn start-local command present in each example's directory. See vite.config.local.mjs for details.

Working with other vis.gl dependencies

Deck.gl has a number of dependencies that fall under vis.gl, and there may be times when it is necessary to make a change in one of these. Thus for development it is necessary to checkout a copy of such a dependency and make local changes.

When running an example using yarn start-local you can use local version of luma.gl or math.gl by appending the --env.local-luma or --env.local-math option.

It is possible to test against the local source of other dependency libraries by modifying examples/vite.config.local.mjs.

Community Governance

vis.gl is part of the OpenJS Foundation. See the organization's Technical Charter.

Technical Steering Committee

deck.gl development is governed by the vis.gl Technical Steering Committee (TSC). Current members:

Xiaoji Chen - chairperson
Ib Green
Felix Palmer
Chris Gervang

Maintainers

Andrew Duberstein - pydeck, json
Xintong Xia - layers
Georgios Karnas - glTF
Kyle Barron - tiles
Dario D'Amico - ArcGIS
Javier Aragón - MVT, CARTO
Ilan Gold - tiles

Maintainers of deck.gl have commit access to this GitHub repository, and take part in the decision making process.

If you are interested in becoming a maintainer, read the governance guidelines.

The vis.gl TSC meets monthly and publishes meeting notes via a mailing list. This mailing list can also be utilized to reach out to the TSC.

Code of Conduct

Please be mindful of and adhere to the Linux Foundation's Code of Conduct when contributing to deck.gl.

Troubleshooting

Develop on Linux

To run the test suite, you may need to install additional dependencies (verified on Ubuntu LTS):

headless-gl dependencies for the Node tests
puppeteer dependencies for the integration tests

Verify that everything works by running yarn test.

Develop on Windows

It's possible to set up the dev environment in Windows Subsystem for Linux.

To run the Node tests, you need to set up OpenGL support via X11 forwarding:

Install VcXsrv.
Run xlaunch.exe, choose multiple windows, display 0, start no client, disable native opengl, disable access control. reference
If working with WSL2, allow WSL to access your X server with firewall rules.

Set the DISPLAY environment variable:

# WSL 1
export DISPLAY=localhost:0
# WSL 2
export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0.0

You can test that it is set up successfully with:

sudo apt-get install mesa-utils
glxgears

You should see a window open with gears turning at this point.

Follow instructions for developing on linux.

Develop on MacOs on Apple Silicon (M1 chip)

To install dependencies specify that you explicitly need the arm64 version

arch -arm64 brew install pkg-config cairo pango libpng jpeg giflib librsvg

You also need a system-wide Python available (python). For example, it can be installed using Homebrew and then symlinked:

brew install python
sudo ln -s /opt/homebrew/bin/python3 /opt/homebrew/bin/python

After this yarn bootstrap can be run with

CPLUS_INCLUDE_PATH=/opt/homebrew/include yarn bootstrap

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!