Skip to main content

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.

git checkout master
yarn bootstrap
yarn test

See additional instructions for Windows, Linux and Apple M1.

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:

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:

Maintainers​

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):

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