1287 library assets url (#1479)

related to issue:
[1287](RaspberryPiFoundation/digital-editor-issues#1287)

Author: DNR500

.env.example

@@ -7,3 +7,5 @@ HTML_RENDERER_URL='http://localhost:3011'
 REACT_APP_GOOGLE_TAG_MANAGER_ID=''
 REACT_APP_API_ENDPOINT='http://localhost:3009'
 REACT_APP_ALLOWED_IFRAME_ORIGINS='http://localhost:3011,http://localhost:3012,http://classroom.localhost:3012'
+
+

.github/workflows/ci-cd.yml

@@ -10,9 +10,16 @@ on:
     branches:
       - "**"
 
+permissions:
+  contents: read
+  packages: read
+
 jobs:
   lint:
     runs-on: ubuntu-latest
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NPM_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -39,8 +46,6 @@ jobs:
 
       - name: Install code
         run: yarn install --immutable
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: eslint
         run: yarn lint
@@ -51,6 +56,9 @@ jobs:
 
   test:
     runs-on: ubuntu-latest
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NPM_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v1
@@ -66,8 +74,6 @@ jobs:
 
       - name: Install code
         run: yarn install --immutable
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run tests
         run: yarn run test --coverage --maxWorkers=4 --workerThreads=true --reporters=default --reporters=jest-junit --reporters=jest-github-actions-reporter
@@ -81,6 +87,9 @@ jobs:
 
   test-cypress:
     runs-on: ubuntu-latest
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NPM_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v1
@@ -96,8 +105,6 @@ jobs:
 
       - name: Install code
         run: yarn install --immutable
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Cypress run
         uses: cypress-io/github-action@v7

.github/workflows/deploy.yml

@@ -114,6 +114,8 @@ jobs:
       url: ${{ needs.setup-environment.outputs.public_url }}
     env:
       HAS_CLOUDFLARE_SECRETS: ${{ secrets.CLOUDFLARE_ZONE_ID != '' && secrets.CLOUDFLARE_API_TOKEN != '' }}
+      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NPM_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Check deployment path
         run: |
@@ -134,8 +136,6 @@ jobs:
 
       - name: Install code
         run: yarn install --immutable
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build WC and HTML renderer bundles
         run: yarn build

.npmrc

@@ -0,0 +1,2 @@
+@RaspberryPiFoundation:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}

.yarnrc.yml

@@ -8,8 +8,14 @@ nodeLinker: node-modules
 
 yarnPath: .yarn/releases/yarn-4.12.0.cjs
 
+npmScopes:
+  RaspberryPiFoundation:
+    npmRegistryServer: "https://npm.pkg.github.com"
+    npmAuthToken: "${NPM_AUTH_TOKEN:-}"
+
 npmMinimalAgeGate: 7d
 
 npmPreapprovedPackages:
   - "@raspberrypifoundation/design-system-react"
-  - "@raspberrypifoundation/design-system-core"
+  - "@raspberrypifoundation/design-system-core"
+  - "@RaspberryPiFoundation/scratch-gui"

README.md

@@ -4,14 +4,47 @@ This project provides a web component containing the Raspberry Pi Code Editor fo
 
 ## Install dependencies
 
-This repository uses Yarn (see `package.json` → `packageManager`). Please install dependencies with Yarn:
+This repository uses Yarn (see `package.json` → `packageManager`).
+
+`@RaspberryPiFoundation/scratch-gui` is installed from [GitHub Packages](https://github.com/RaspberryPiFoundation/scratch-editor/pkgs/npm/scratch-gui). Complete the steps below, then run `yarn install`.
+
+### Set a personal access token
+
+If you don't already have this set up you will need it to access deps in the RPF private registry
+
+1. On GitHub, create a **classic** personal access token: [Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens). Enable **`read:packages`** and **`repo`**. For packages tied to private repositories, `read:packages` alone can cause `yarn install` to fail with `401`/`403`.
+2. If your organisation uses SAML SSO, open the token on GitHub and **Authorize** it for **RaspberryPiFoundation** (Configure SSO).
+3. Add the token to your shell profile (for example `~/.zshrc` on macOS):
+
+   ```bash
+   export GITHUB_TOKEN=ghp_your_token_here
+   export NPM_AUTH_TOKEN=$GITHUB_TOKEN
+   ```
+
+   Replace `ghp_your_token_here` with your token.
+
+4. Load the profile in any terminal you are currently using for this project:
+
+   ```bash
+   source ~/.zshrc
+   ```
+
+5. Confirm GitHub Packages is reachable from this directory:
+
+   ```bash
+   yarn npm info @RaspberryPiFoundation/scratch-gui version
+   ```
+
+   You should see the version pinned in `package.json` (for example `13.7.3-code-classroom.20260522151700`), not an authentication error. If you see `unauthenticated` or `401`, run `source ~/.zshrc` again or check the token scopes and SSO authorisation.
+
+6. When you use Docker, run `docker compose up` from a shell where `NPM_AUTH_TOKEN` is set. Compose passes it from the host into the container so `yarn install` can run there too.
+
+Then install dependencies:
 
 ```
 yarn install
 ```
 
-Using `npm install` can fail due to strict peer-dependency resolution in npm for some legacy packages in this project.
-
 ## Environment variables
 
 The app uses the `dotenv` package to provide access to environment variables. Copy the example file into `.env` and use this file for any other environment variables the web component may require:
@@ -227,6 +260,10 @@ Python code snippets are styled and syntax-highlighted using the `language-pytho
 <code class="language-python">print('hello world')</code>
 ```
 
+### Linking a local scratch-editor (Scratch GUI)
+
+See [docs/linking-scratch-editor.md](./docs/linking-scratch-editor.md) for local scratch-editor linking instructions.
+
 ## Deployment
 
 Deployment is managed through Github actions. The UI is deployed to staging and production environments through an S3 bucket, managed via Cloudflare. This requires the following environment variables to be set

docker-compose.yml

@@ -1,6 +1,8 @@
 x-app: &x-app
   build:
     context: .
+  environment:
+    NPM_AUTH_TOKEN: ${NPM_AUTH_TOKEN}
   volumes:
     - .:/app
     - node_modules:/app/node_modules

docs/linking-scratch-editor.md

@@ -0,0 +1,103 @@
+# Linking a local scratch-editor (Scratch GUI)
+
+When you are working on the [Raspberry Pi Foundation scratch-editor](https://github.com/RaspberryPiFoundation/scratch-editor) fork (for example changes to `scratch-gui`), you may want editor-ui to load that build instead of the `@RaspberryPiFoundation/scratch-gui` version from GitHub Packages.
+
+**Use the `code-classroom` branch** in scratch-editor as your base for editor-ui work. That branch is the integration line for this editor (RPF packaging, publish, and GUI props such as `libraryAssetUrlTemplate`). Check it out before you link or build:
+
+```bash
+cd ../scratch-editor
+git fetch origin
+git checkout code-classroom
+```
+
+Feature work should branch from `code-classroom`, not from upstream `main` or `code-classroom-base`.
+
+editor-ui does not bundle Scratch GUI into the main webpack app. It copies a prebuilt `dist/scratch-gui.js` (and static assets) from `node_modules` into the dev server output. Pointing the dependency at your local clone is enough to test GUI changes in the Scratch iframe.
+
+**Do not commit these linking changes.** They are temporary for local development only. These changes to `package.json`, `yarn.lock`, and `docker-compose.yml` are for local development only.
+
+## Repository layout
+
+Clone both repositories as siblings:
+
+```text
+Development/
+  editor-ui/
+  scratch-editor/    ← github.com/RaspberryPiFoundation/scratch-editor
+```
+
+## Temporary changes in editor-ui
+
+**1. `package.json`** — replace the GitHub Packages dependency with a file link (the name must match the package in scratch-editor):
+
+```json
+"@RaspberryPiFoundation/scratch-gui": "file:../scratch-editor/packages/scratch-gui"
+```
+
+**2. `docker-compose.yml`** — mount the scratch-editor repo into the container (read-only):
+
+```yaml
+volumes:
+  - .:/app
+  - ../scratch-editor:/scratch-editor:ro
+  - node_modules:/app/node_modules
+```
+
+From `/app` in the container, `file:../scratch-editor/packages/scratch-gui` resolves to `/scratch-editor/packages/scratch-gui` on the mounted volume.
+
+**3. `yarn.lock`** — run `yarn install` inside Docker (see below) and commit nothing; the lockfile will change while the link is active. Revert it when you restore the GitHub Packages version in `package.json`.
+
+## Build scratch-gui
+
+Build on your machine (the `scratch-editor` mount is read-only inside the editor-ui container):
+
+```bash
+cd ../scratch-editor
+nvm install
+nvm use
+NODE_ENV=development npm ci
+npm run build
+```
+
+After every scratch-gui code change, run the build again, then restart the editor-ui container so webpack copies the new `dist/scratch-gui.js`.
+
+## Run with Docker
+
+**editor-api** (Scratch projects and assets API):
+
+```bash
+cd ../editor-api
+docker compose up
+```
+
+**editor-ui**:
+
+```bash
+cd ../editor-ui
+docker compose up
+```
+
+The container runs `yarn install` then `yarn start` on each start. The first start after switching to the file link may take longer while dependencies are linked.
+
+## Verify in the browser
+
+Scratch runs in an iframe served from editor-ui (port **3011**), not from the main web-component bundle alone.
+
+- Web component test page: open a **Scratch** sample, e.g.
+  `http://localhost:3011/web-component.html`
+  then choose **cool-scratch**.
+- **editor-standalone** (port **3012**): also loads the web component from `http://localhost:3011`; open a Scratch project under `/en-US/projects/…` with editor-ui and editor-api running.
+
+## Revert when finished
+
+1. Restore the GitHub Packages pin in `package.json`, for example:
+
+   ```json
+   "@RaspberryPiFoundation/scratch-gui": "13.7.3-code-classroom.20260522151700"
+   ```
+
+   Use the version your branch pins (see [scratch-gui on GitHub Packages](https://github.com/RaspberryPiFoundation/scratch-editor/pkgs/npm/scratch-gui)).
+2. Remove the `../scratch-editor:/scratch-editor:ro` volume from `docker-compose.yml`.
+3. Revert `yarn.lock` (e.g. `git checkout -- yarn.lock`) or run `yarn install` again after restoring `package.json`.
+4. Restart `docker compose up` in editor-ui.
+

package.json

@@ -3,6 +3,7 @@
   "version": "0.34.20",
   "private": true,
   "dependencies": {
+    "@RaspberryPiFoundation/scratch-gui": "13.7.3-code-classroom.20260522151700",
     "@apollo/client": "^3.7.8",
     "@babel/core": "^7.17.10",
     "@codemirror/commands": "^6.1.1",
@@ -20,7 +21,6 @@
     "@react-three/fiber": "^8.0.13",
     "@reduxjs/toolkit": "^1.6.2",
     "@replit/codemirror-indentation-markers": "^6.1.0",
-    "@scratch/scratch-gui": "^13.0.0",
     "@sentry/browser": "^7.17.3",
     "@sentry/react": "7.16.0",
     "@sentry/tracing": "7.16.0",

src/components/ScratchEditor/ScratchEditor.jsx

@@ -4,6 +4,10 @@ import { useCallback, useRef, useEffect, useState } from "react";
 import WrapperdScratchGui from "./WrappedScratchGui.jsx";
 import { postScratchGuiEvent, allowedParentOrigin } from "./events.js";
 
+/** Scratch library picker assets (not project save/load — those use editor-api). */
+export const SCRATCH_LIBRARY_ASSET_URL_TEMPLATE =
+  "https://editor-assets.raspberrypi.org/internalapi/asset/{assetPath}/get/";
+
 const handleUpdateProjectId = (updatedProjectId) => {
   postScratchGuiEvent("scratch-gui-project-id-updated", {
     projectId: updatedProjectId,
@@ -79,6 +83,7 @@ const ScratchEditor = ({
       menuBarHidden={true}
       projectHost={`${apiUrl}/api/scratch/projects`}
       assetHost={`${apiUrl}/api/scratch/assets`}
+      libraryAssetUrlTemplate={SCRATCH_LIBRARY_ASSET_URL_TEMPLATE}
       basePath={`${process.env.ASSETS_URL}/scratch-gui/`}
       onStorageInit={(storage) => {
         scratchFetchApiRef.current = storage.scratchFetch;