chore: Move to yarn 4 and workspaces

.github/workflows/release.yml

@@ -48,13 +48,25 @@ jobs:
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version-file: '.nvmrc'
-          cache: 'yarn'
 
-      - name: Enable Corepack
-        run: corepack enable yarn
+      - name: Enable Corepack / Yarn 4
+        run: |
+          corepack enable
+          corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+          yarn -v
+
+      - name: Cache Yarn 4 artifacts
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.yarn/berry/cache
+            .yarn/install-state.gz
+          key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml', 'package.json') }}
 
       - name: Install dependencies
-        run: yarn
+        run: |
+          yarn install --immutable
+          yarn bootstrap
 
       - name: Build packages
         run: yarn build

.github/workflows/test.yml

@@ -24,13 +24,25 @@ jobs:
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version-file: '.nvmrc'
-          cache: 'yarn'
 
-      - name: Enable Corepack
-        run: corepack enable yarn
+      - name: Enable Corepack / Yarn 4
+        run: |
+          corepack enable
+          corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+          yarn -v
+
+      - name: Cache Yarn 4 artifacts
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.yarn/berry/cache
+            .yarn/install-state.gz
+          key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml', 'package.json') }}
 
       - name: Install dependencies
-        run: yarn bootstrap
+        run: |
+          yarn install --immutable
+          yarn bootstrap
 
       - name: Build packages
         run: yarn build
@@ -73,13 +85,27 @@ jobs:
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version-file: '.nvmrc'
-          cache: 'yarn'
 
-      - name: Enable Corepack
-        run: corepack enable yarn
+      - name: Enable Corepack / Yarn 4
+        run: |
+          corepack enable
+          corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+          yarn -v
+
+      - name: Cache Yarn 4 artifacts
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.yarn/berry/cache
+            .yarn/install-state.gz
+            website/.yarn/cache
+            website/.yarn/install-state.gz
+          key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml', 'package.json', 'website/yarn.lock', 'website/.yarnrc.yml', 'website/package.json') }}
 
       - name: Install dependencies
-        run: yarn bootstrap
+        run: |
+          yarn install --immutable
+          yarn bootstrap
 
       - name: Build packages
         run: yarn build
@@ -97,16 +123,28 @@ jobs:
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version-file: '.nvmrc'
-          cache: 'yarn'
 
-      - name: Enable Corepack
-        run: corepack enable yarn
+      - name: Enable Corepack / Yarn 4
+        run: |
+          corepack enable
+          corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+          yarn -v
+
+      - name: Cache Yarn 4 artifacts
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.yarn/berry/cache
+            .yarn/install-state.gz
+          key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml', 'package.json') }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
 
       - name: Install dependencies
         run: |
+          yarn install --immutable
+          yarn bootstrap
           cd bindings/pydeck
           make setup-env
           make init

.github/workflows/website.yml

@@ -36,15 +36,28 @@ jobs:
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version-file: '.nvmrc'
-          cache: 'yarn'
 
-      - name: Enable Corepack
-        run: corepack enable yarn
+      - name: Enable Corepack / Yarn 4
+        run: |
+          corepack enable
+          corepack prepare "$(node -p "require('./package.json').packageManager")" --activate
+          yarn -v
+
+      - name: Cache Yarn 4 artifacts
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.yarn/berry/cache
+            .yarn/install-state.gz
+            website/.yarn/cache
+            website/.yarn/install-state.gz
+          key: ${{ runner.os }}-yarn4-${{ hashFiles('yarn.lock', '.yarnrc.yml', 'package.json', 'website/yarn.lock', 'website/.yarnrc.yml', 'website/package.json') }}
 
       - name: Install dependencies
         run: |
+          yarn install --immutable
           yarn bootstrap
-          (cd website && yarn)
+          (cd website && yarn install --immutable)
 
       - name: Build website
         env:

.gitignore

@@ -27,6 +27,15 @@ showcases/**/yarn.lock
 test/**/yarn.lock
 yarn-error.log
 package-lock.json
+.pnp.*
+.yarn/*
+!.yarn/cache
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+*/**/.yarn/*
 
 .claude/
 .vscode/

.yarnrc.yml

@@ -0,0 +1,50 @@
+enableScripts: true
+
+nodeLinker: node-modules
+
+logFilters:
+  - code: YN0060
+    pattern: "*@types/react is listed by your project with version 18.3.28*"
+    level: discard
+  - code: YN0060
+    pattern: "*react is listed by your project with version 18.3.1*"
+    level: discard
+  - code: YN0060
+    pattern: "*react-dom is listed by your project with version 18.3.1*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @deck.gl/extensions*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @deck.gl/mesh-layers*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @loaders.gl/core*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @luma.gl/core*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @luma.gl/engine*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @luma.gl/shadertools*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @luma.gl/webgl*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide @luma.gl/webgpu*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide esri-loader*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide react*"
+    level: discard
+  - code: YN0002
+    pattern: "*doesn't provide react-dom*"
+    level: discard
+  - code: YN0086
+    pattern: "*Some peer dependencies are incorrectly met*"
+    level: discard

CONTRIBUTING.md

@@ -57,8 +57,9 @@ yarn start
 Run the layer browser application:
 
 ```bash
+cd deck.gl
+yarn install
 cd examples/layer-browser
-yarn
 yarn start-local
 ```
 
@@ -71,7 +72,7 @@ If you consider opening a PR, here is some documentation to get you started:
 
 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](https://github.com/visgl/deck.gl/blob/master/examples/vite.config.local.mjs) for details.
+To do so, run `yarn install` once from the repository root, then use the `yarn start-local` command present in each example's directory. See [vite.config.local.mjs](https://github.com/visgl/deck.gl/blob/master/examples/vite.config.local.mjs) for details.
 
 ### Working with other vis.gl dependencies
 

docs/get-started/getting-started.md

@@ -19,9 +19,9 @@ The [deck.gl](https://www.npmjs.com/package/deck.gl) module includes all deck.gl
 
 ## Running the Examples
 
-The deck.gl repository contains an [examples folder](https://github.com/visgl/deck.gl/tree/master/examples) with a selection of small, standalone examples that could be good starting points for your application.
+The deck.gl repository contains an [examples folder](https://github.com/visgl/deck.gl/tree/master/examples) with a selection of small examples that could be good starting points for your application.
 
-You should be able to copy these folders to your preferred locations, and get them running simply as follows:
+Package-managed examples in this repository are installed as Yarn workspaces from the repository root. If you copy an example into a separate project, replace any `workspace:*` deck.gl dependencies with published version ranges before installing it outside this monorepo.
 
 Clone the deck.gl repo, if you haven't already
 
@@ -35,41 +35,33 @@ For most consistent results, it is recommended that you check out the latest rel
 git checkout 8.0-release
 ```
 
-Change directory to the example you are interested in, e.g.
+Install dependencies once from the deck.gl repository root:
 
 ```bash
-cd deck.gl/examples/get-started/pure-js/basic
+cd deck.gl
+yarn install
 ```
 
-Then install dependencies using the installer of your choice:
+Change directory to the example you are interested in and start it:
 
 ```bash
-npm install
-# or
-yarn
-```
-
-and then running using:
-
-```bash
-npm start
+cd examples/get-started/pure-js/basic
+yarn start
 ```
 
 If the example uses a mapbox base map you need a [Mapbox access token](./using-with-map.md)
 
 ```bash
-export MapboxAccessToken={Your Token Here} && npm start
+export MapboxAccessToken={Your Token Here} && yarn start
 ```
 
 If you want to build the example against the latest deck.gl source code in the cloned repo (rather than the published version of deck.gl listed in the examples `package.json`)
 
 ```bash
-npm run start-local
+yarn start-local
 ```
 
-> The examples on the `master` branch are updated to use features from the latest, unreleased version of deck.gl. If some example doesn't work using `npm start` it can be worth trying `npm run start-local`.
-
-> While all examples support `npm run start-local`, there are some caveats when running against local source. Most importantly, you must make sure to run `npm install` or `yarn` in the deck.gl root folder before running `npm run start-local` in an example folder.
+> The examples on the `master` branch are updated to use features from the latest, unreleased version of deck.gl. If some example doesn't work using `yarn start` it can be worth trying `yarn start-local`.
 
 
 ## Selectively Install Dependencies

examples/README.md

@@ -1,9 +1,9 @@
 # deck.gl Examples
 
-All deck.gl examples are set up to be "stand-alone", which means that
-you can copy the example folder to your own environment, run `yarn` or `npm install`
-and `npm start` and within minutes have a running, minimal app that you can
-start modifying and experimenting with.
+Package-managed deck.gl examples are installed as Yarn workspaces from the
+repository root. You can still copy an example folder to your own project, but
+replace any `workspace:*` deck.gl dependencies with published version ranges
+before installing it outside this monorepo.
 
 ## Examples Catalog
 
@@ -50,15 +50,27 @@ These are examples that use experimental deck.gl features, or implement features
 
 ## Installing and Running
 
-Most example apps can be run by installing the dependencies with either `yarn` or with `npm install`, then `npm run start`. Refer to the README in each example directory for app-specific instructions.
+Install dependencies once from the deck.gl repository root:
+
+```bash
+yarn install
+```
+
+Then run an example from its own directory:
+
+```bash
+cd examples/get-started/pure-js/basic
+yarn start
+```
+
+Refer to the README in each example directory for app-specific instructions.
 
 
 ### Running Examples Against deck.gl Source Code
 
-Most examples are set up so that they can be run either
-against the local source code (enabling debugging of deck.gl itself,
-with hot reloading) or against an installed version of deck.gl
-(enables testing that things work with the published version).
+Examples that support local-source development have a `start-local` script in
+their `package.json`:
 
-Examples that support this mode have a `start-local` script in their
-`package.json`.
+```bash
+yarn start-local
+```

examples/basemap-browser/README.md

@@ -38,8 +38,10 @@ src/
 ## Usage
 
 ```bash
-# From the examples/basemap-browser directory
-yarn
+# From the deck.gl repository root
+yarn install
+
+cd examples/basemap-browser
 yarn start-local
 ```
 

examples/basemap-browser/package.json

@@ -8,12 +8,12 @@
     "start-local": "vite --config ../vite.config.local.mjs"
   },
   "dependencies": {
-    "@deck.gl/core": "^9.2.0",
-    "@deck.gl/google-maps": "^9.2.0",
-    "@deck.gl/extensions": "^9.2.0",
-    "@deck.gl/geo-layers": "^9.2.0",
-    "@deck.gl/layers": "^9.2.0",
-    "@deck.gl/mapbox": "^9.2.0",
+    "@deck.gl/core": "workspace:*",
+    "@deck.gl/extensions": "workspace:*",
+    "@deck.gl/geo-layers": "workspace:*",
+    "@deck.gl/google-maps": "workspace:*",
+    "@deck.gl/layers": "workspace:*",
+    "@deck.gl/mapbox": "workspace:*",
     "@vis.gl/react-google-maps": "^1.7.1",
     "mapbox-gl": "^3.8.0",
     "maplibre-gl": "^5.0.0",