Automate frontend builds for releases; stop committing the build

.github/workflows/release.yml

@@ -36,10 +36,14 @@ jobs:
     if: needs.release.outputs.is-release == 'true'
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
       - uses: compas-dev/compas-actions/prepare-release@v1
         with:
           python-version: "3.11"
           management-tool: uv
+          run-prebuild: "true"
 
   publish:
     needs: [release, prepare]

.gitignore

@@ -334,6 +334,7 @@ storybook-static/
 temp/
 
 
-# Frontend is built from external repo and committed to this repo
-# Uncomment the line below if you want to gitignore the frontend build:
-# src/compas_threejs/viewer/frontend/
+# Frontend is built from the compas_threejs_ts release pinned in FRONTEND_VERSION.
+# Run `invoke pre-build` (CI/release) or `invoke sync-frontend` (local dev against
+# a sibling checkout) to populate it -- see FRONTEND_WORKFLOW.md.
+src/compas_threejs/viewer/frontend/

CHANGELOG.md

@@ -11,8 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- The bundled frontend is no longer committed to the repository. It's now built automatically at release time from the `compas_threejs_ts` version pinned in `FRONTEND_VERSION`, via a new `invoke pre-build` task wired into the release pipeline (`run-prebuild` on `prepare-release@v1`). `pip install compas_threejs` still requires no Node.js. See `FRONTEND_WORKFLOW.md`.
+
 ### Removed
 
+- `scripts/sync-frontend.py` and `sync-frontend.bat`, superseded by the `invoke sync-frontend` task.
 
 ## [1.0.1] - 2026-08-13
 

CONTRIBUTING.md

@@ -82,15 +82,20 @@ If you modify the sibling `compas_threejs_ts` repository:
    cd ../compas_threejs
    invoke sync-frontend
    ```
-3. Commit the TypeScript source in its repository and the generated files under
-   `src/compas_threejs/viewer/frontend/` in this repository.
+3. Commit and release the TypeScript source in its own repository. The build
+   `invoke sync-frontend` copied in is only for local testing here -- it is **not**
+   committed to this repository (see [FRONTEND_WORKFLOW.md](FRONTEND_WORKFLOW.md)).
+4. Once `compas_threejs_ts` has a new tagged release, bump
+   [`FRONTEND_VERSION`](FRONTEND_VERSION) in this repository to that version, verify
+   with `invoke pre-build`, and commit the bump as its own reviewable PR.
 
 ## Releasing (maintainers)
 
 Start from a clean, up-to-date `main` branch with all changes listed under
 `Unreleased` in `CHANGELOG.md`, then run:
 
 ```bash
+invoke pre-build
 invoke release --release-type=minor
 ```
 
@@ -99,6 +104,13 @@ version and changelog, commits and tags the release, builds the distributions,
 prepares the next `Unreleased` section, and asks before pushing. Pushing the tag
 triggers the Trusted Publishing workflow.
 
+`invoke pre-build` builds the `compas_threejs_ts` release pinned in
+[`FRONTEND_VERSION`](FRONTEND_VERSION) and vendors it into
+`src/compas_threejs/viewer/frontend/` so the distributions built by `invoke release`
+bundle it -- `invoke release` does not do this on its own. The automated GitHub
+Actions release pipeline runs the equivalent step itself, so this manual step is only
+needed for local releases.
+
 ## Submitting Changes
 
 1. **Push your branch** to your fork:

FRONTEND_VERSION

@@ -0,0 +1 @@
+1.2.0

FRONTEND_WORKFLOW.md

@@ -7,117 +7,89 @@ The frontend for `compas_threejs` has been moved to a separate repository for in
 - **Backend (this repo)**: `compas_threejs` - Python package with FastAPI server
 - **Frontend (separate repo)**: `compas_threejs_ts` - Vue.js + Three.js viewer application
 
-## Development Workflow
+The built frontend (`src/compas_threejs/viewer/frontend/`) is **not** committed to this
+repo. It's generated on demand by one of two invoke tasks, and it's `.gitignore`d.
+That means a fresh clone has no working viewer until you run one of them once.
 
-### 1. Frontend Development
+## Two ways to get a built frontend
 
-Work in the separate frontend repository:
+### `invoke pre-build` — reproduces a release build
 
-```bash
-cd ../compas_threejs_ts
-npm run dev  # Start development server
-```
-
-Make your changes, commit them to the frontend repo.
+Clones `compas_threejs_ts` at the tag recorded in [`FRONTEND_VERSION`](FRONTEND_VERSION),
+builds it, and copies `dist/` into `src/compas_threejs/viewer/frontend/`. This is
+exactly what the release pipeline runs (see "Releasing" below), so it's the way to
+reproduce locally what a `pip install compas_threejs` will actually ship. No sibling
+checkout needed — it clones a throwaway copy into a temp directory.
 
-### 2. Sync Frontend Build to Backend
-
-After making frontend changes, sync the build to this Python package:
-
-**Windows:**
 ```bash
-sync-frontend.bat
+invoke pre-build
 ```
 
-**Linux/Mac or from Python:**
-```bash
-python scripts/sync-frontend.py
-```
-
-**Or with invoke (if installed):**
-```bash
-invoke sync-frontend
-```
+Use this when you just want a working viewer, or when verifying a `FRONTEND_VERSION`
+bump before committing it.
 
-This will:
-1. Build the frontend from `../compas_threejs_ts`
-2. Clear the old build from `src/compas_threejs/viewer/frontend/`
-3. Copy the new build files
+### `invoke sync-frontend` — fast loop against a local frontend checkout
 
-### 3. Test the Integration
+Builds whatever is currently checked out in a sibling `../compas_threejs_ts` directory
+and copies its `dist/` in. Ignores `FRONTEND_VERSION` entirely — it always reflects
+your local working tree, including uncommitted changes.
 
 ```bash
-# Run your Python examples to test the viewer
-python examples/your_example.py
+cd ../compas_threejs_ts
+npm run dev   # iterate here first if you like
+cd ../compas_threejs
+invoke sync-frontend
+python examples/your_example.py   # test the integration
 ```
 
-The viewer should open in your browser with the updated frontend.
+Use this while actively developing `compas_threejs_ts` itself.
 
-### 4. Commit Both Repos
+Both tasks need Node.js available on `PATH` (see `compas_threejs_ts`'s `package.json`
+`engines` field for the minimum version) and, for `sync-frontend`, expect the Python
+and TypeScript repositories to be sibling directories.
 
-**Frontend repo:**
-```bash
-cd ../compas_threejs_ts
-git add .
-git commit -m "Your frontend changes"
-git push
-```
+## Picking up a new compas_threejs_ts release
 
-**Backend repo (after syncing):**
-```bash
-cd ../compas_threejs
-git add src/compas_threejs/viewer/frontend/
-git commit -m "Update frontend build"
-git push
-```
-
-The frontend build **is committed** to the backend repo so users can install via pip without needing Node.js.
+1. Finish and release the change in `compas_threejs_ts` (tagged `vX.Y.Z`, published to npm).
+2. In `compas_threejs`, edit [`FRONTEND_VERSION`](FRONTEND_VERSION) to `X.Y.Z`.
+3. Run `invoke pre-build` and test (`pytest`, `python examples/your_example.py`).
+4. Commit the `FRONTEND_VERSION` bump. Do **not** commit the generated
+   `src/compas_threejs/viewer/frontend/` directory — it's gitignored on purpose.
 
-## Important Notes
+Pinning the version this way (rather than always building whatever is newest) is
+deliberate: `compas_threejs_ts` and this package share a wire-format contract via
+`compas-pb`/`compas-pb-ts`, and an unreviewed frontend bump could silently break that
+contract. Bumping `FRONTEND_VERSION` is a normal, reviewable PR.
 
-### Current Setup
-- Frontend build **is committed** in this repo for easier pip installation
-- You must run `sync-frontend.bat` or `python scripts/sync-frontend.py` to update the viewer
-- The Python and TypeScript repositories must be sibling directories
-- Users installing via pip don't need Node.js
+## Releasing (maintainers)
 
-### Path Configuration
-The sync script expects:
-- Frontend repo: `../compas_threejs_ts/` (relative to this repo)
-- Output location: `src/compas_threejs/viewer/frontend/`
+The GitHub Actions release pipeline (`.github/workflows/release.yml`) builds the
+frontend automatically: the `prepare` job sets up Node.js and calls
+`compas-dev/compas-actions/prepare-release@v1` with `run-prebuild: "true"`, which runs
+`invoke pre-build` before building the sdist/wheel. So published distributions always
+bundle the frontend pinned in `FRONTEND_VERSION` at release time, and `pip install
+compas_threejs` never needs Node.js on the end user's machine.
 
-If you move repositories, update the path in `scripts/sync-frontend.py`.
+If you release locally instead (e.g. via `invoke release`), run `invoke pre-build`
+first — that path does not run it for you.
 
 ## Troubleshooting
 
-### "FileNotFoundError" when running sync script
-- Ensure `../compas_threejs_ts` exists and contains `package.json`
-- Check that npm is installed and available
+### "npm was not found on PATH"
 
-### "PlaneHelpers" import warnings during build
-- These are non-fatal warnings from Three.js imports
-- The build will still succeed
+Install Node.js (matching `compas_threejs_ts`'s `engines.node` requirement) and make
+sure `npm` is on `PATH`.
 
-### Large bundle size warning
-- Consider code-splitting in the frontend if bundle grows too large
-- See: https://rollupjs.org/configuration-options/#output-manualchunks
+### `invoke pre-build` fails to clone
 
-## Future Improvements
+Check that `FRONTEND_VERSION` names a tag that actually exists on
+`compas_threejs_ts` (tags are `vX.Y.Z`, e.g. `v1.2.0`).
 
-### Option A: Publish Frontend to npm
-1. Publish `compas_threejs_ts` as an npm package
-2. Backend downloads it during Python package build
-3. Most decoupled approach
+### "PlaneHelpers" import warnings during build
 
-### Option B: Git Submodule
-1. Add frontend as a git submodule
-2. Build during Python package installation
-3. Users need Node.js installed
+These are non-fatal warnings from Three.js imports. The build will still succeed.
 
-### Option C: Commit Built Frontend ✅ **CURRENT**
-1. Run sync script before commits
-2. Commit built files to backend repo
-3. No Node.js required for users
-4. Larger git history due to binary files
+### Large bundle size warning
 
-**Current strategy**: Option C. This keeps installation simple for end users.
+Consider code-splitting in the frontend if the bundle grows too large. See:
+https://rollupjs.org/configuration-options/#output-manualchunks

docs/installation.md

@@ -25,6 +25,11 @@ cd compas_threejs
 pip install -e ".[dev]"
 ```
 
+The built frontend isn't committed to this repo, so the viewer won't render yet.
+Run `invoke pre-build` to fetch and build the pinned `compas_threejs_ts` release (no
+extra clone needed), or see below to build against a local frontend checkout instead.
+See [FRONTEND_WORKFLOW.md](../FRONTEND_WORKFLOW.md) for details.
+
 ### Typescript Frontend
 
 The TypeScript viewer lives in a separate repository. Clone it next to the