Sandcastle build config updates

.github/workflows/deploy.yml

@@ -2,7 +2,7 @@ name: deploy
 on:
   push:
     branches-ignore:
-      - 'cesium.com'
+      - "cesium.com"
       - production
 concurrency:
   group: deploy-${{ github.ref }}
@@ -22,14 +22,13 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       GITHUB_REPO: ${{ github.repository }}
       GITHUB_SHA: ${{ github.sha }}
-      BASE_URL: /cesium/${{ github.ref_name }}/
       DEPLOYED_URL: https://ci-builds.cesium.com/cesium/${{ github.ref_name }}/
     steps:
       - uses: actions/checkout@v5
       - name: install node 22
         uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: "22"
       - name: npm install
         run: npm install
       - name: set the version in package.json
@@ -42,8 +41,6 @@ jobs:
         run: npm pack --workspaces &> /dev/null
       - name: build apps
         run: npm run build-apps
-      - name: build sandcastle v2
-        run: npm run build-ci -w packages/sandcastle -- -l warn
       - uses: ./.github/actions/verify-package
       - name: deploy to s3
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}

.github/workflows/prod.yml

@@ -41,14 +41,17 @@ jobs:
         run: npm install
       - name: build website release
         run: npm run website-release
-      - name: build apps
-        run: npm run build-apps
       - name: build types
         run: npm run build-ts
-      - name: build prod sandcastle
-        run: npm run build-prod -w packages/sandcastle -- -l warn
+      - name: build apps
+        run: npm run build-apps
       - name: deploy to cesium.com
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}
+        # Download zip from the Github release and unzip to Build/release/
+        # Publish that unzipped code to the bucket for https://cesium.com/downloads/cesiumjs/releases/[version]/... urls
+        # Publish the documentation files to the bucket for https://cesium.com/learn/cesiumjs/ref-doc/
+        # Publish the simple viewer app to the bucket for https://cesium.com/cesiumjs/cesium-viewer/
+        # Publish sandcastle to the bucket for https://sandcastle.cesium.com/
         run: |
           curl -LO $(curl https://api.github.com/repos/CesiumGS/cesium/releases/latest -H "Authorization: ${GITHUB_TOKEN}" | jq -r '.assets[0].browser_download_url')
           unzip Cesium-$(cat package.json | jq -r '.version' | sed 's/\.0$//').zip -d Build/release/ -x "Apps"

.github/workflows/sandcastle-dev.yml

@@ -2,7 +2,7 @@ name: sandcastle-dev
 on:
   push:
     branches:
-      - 'cesium.com'
+      - "main"
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -20,15 +20,15 @@ jobs:
       - name: install node 22
         uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: "22"
       - name: npm install
         run: npm install
       - name: build website release
         run: npm run website-release
       - name: build types
         run: npm run build-ts
       - name: build prod sandcastle
-        run: npm run build-prod -w packages/sandcastle -- -l warn
+        run: npm run build-sandcastle
       - name: deploy to dev-sandcastle.cesium.com
         if: ${{ env.AWS_ACCESS_KEY_ID != '' }}
         run: |

.npmignore

@@ -23,6 +23,8 @@
 /scripts/
 /favicon.ico
 /gulpfile.js
+/gulpfile.apps.js
+/gulpfile.makezip.js
 /index.html
 /index.release.html
 /launches

Documentation/Contributors/BuildGuide/README.md

@@ -77,7 +77,7 @@ npm start
 Then browse to [http://localhost:8080/](http://localhost:8080/). The landing page includes apps and tools commonly used during development, including:
 
 - **Hello World** : an example for how to create a 3D globe. [Tutorial here](https://cesium.com/learn/cesiumjs-learn/cesiumjs-quickstart/)
-- **Sandcastle** : an app for viewing and creating [code examples](https://sandcastle.cesium.com?src=Hello%20World.html&label=Showcases), complete with a live preview
+- **Sandcastle** : an app for viewing and creating [code examples](https://sandcastle.cesium.com), complete with a live preview
 - **Test Suites** : tests using [Jasmine](https://jasmine.github.io/). [Testing guide here.](https://github.com/CesiumGS/cesium/blob/main/Documentation/Contributors/TestingGuide/README.md#testing-guide)
 - **Documentation** : reference documentation built from source. [Documentation guide here.](https://github.com/CesiumGS/cesium/blob/main/Documentation/Contributors/DocumentationGuide/README.md#documentation-guide)
 

eslint.config.js

@@ -48,6 +48,8 @@ export default [
       "scripts/**/*.js",
       "packages/sandcastle/scripts/**/*.js",
       "gulpfile.js",
+      "gulpfile.apps.js",
+      "gulpfile.makezip.js",
       "server.js",
     ],
     ...configCesium.configs.node,

gulpfile.apps.js

@@ -0,0 +1,252 @@
+import { join } from "path";
+import { finished } from "stream/promises";
+
+import gulp from "gulp";
+import gulpReplace from "gulp-replace";
+import { buildSandcastleApp } from "./scripts/buildSandcastle.js";
+import { mkdirp } from "mkdirp";
+import { bundleWorkers, defaultESBuildOptions } from "./scripts/build.js";
+import { build as esbuild } from "esbuild";
+
+const isProduction = process.env.PROD === "true";
+
+// Print an esbuild warning
+function printBuildWarning({ location, text }) {
+  const { column, file, line, lineText, suggestion } = location;
+
+  let message = `\n
+  > ${file}:${line}:${column}: warning: ${text}
+  ${lineText}
+  `;
+
+  if (suggestion && suggestion !== "") {
+    message += `\n${suggestion}`;
+  }
+
+  console.log(message);
+}
+
+// Ignore `eval` warnings in third-party code we don't have control over
+function handleBuildWarnings(result) {
+  for (const warning of result.warnings) {
+    if (
+      !warning.location.file.includes("protobufjs.js") &&
+      !warning.location.file.includes("Build/Cesium")
+    ) {
+      printBuildWarning(warning);
+    }
+  }
+}
+
+async function buildLegacySandcastle() {
+  const streams = [];
+  let appStream = gulp.src(
+    [
+      "Apps/Sandcastle/**",
+      "!Apps/Sandcastle/load-cesium-es6.js",
+      "!Apps/Sandcastle/images/**",
+      "!Apps/Sandcastle/gallery/**.jpg",
+    ],
+    {
+      encoding: false,
+    },
+  );
+
+  if (isProduction) {
+    // Remove swap out ESM modules for the IIFE build
+    appStream = appStream
+      .pipe(
+        gulpReplace(
+          '    <script type="module" src="../load-cesium-es6.js"></script>',
+          '    <script src="../CesiumUnminified/Cesium.js"></script>\n' +
+            '    <script>window.CESIUM_BASE_URL = "../CesiumUnminified/";</script>',
+        ),
+      )
+      .pipe(
+        gulpReplace(
+          '    <script type="module" src="load-cesium-es6.js"></script>',
+          '    <script src="CesiumUnminified/Cesium.js"></script>\n' +
+            '    <script>window.CESIUM_BASE_URL = "CesiumUnminified/";</script>',
+        ),
+      )
+      // Fix relative paths for new location
+      .pipe(gulpReplace("../../../Build", ".."))
+      .pipe(gulpReplace("../../../Source", "../CesiumUnminified"))
+      .pipe(gulpReplace("../../Source", "."))
+      .pipe(gulpReplace("../../../ThirdParty", "./ThirdParty"))
+      .pipe(gulpReplace("../../ThirdParty", "./ThirdParty"))
+      .pipe(gulpReplace("../ThirdParty", "./ThirdParty"))
+      .pipe(gulpReplace("../Apps/Sandcastle", "."))
+      .pipe(gulpReplace("../../SampleData", "../SampleData"))
+      .pipe(
+        gulpReplace("../../Build/Documentation", "/learn/cesiumjs/ref-doc/"),
+      )
+      .pipe(gulp.dest("Build/Sandcastle"));
+  } else {
+    // Remove swap out ESM modules for the IIFE build
+    appStream = appStream
+      .pipe(
+        gulpReplace(
+          '    <script type="module" src="../load-cesium-es6.js"></script>',
+          '    <script src="../../../Build/CesiumUnminified/Cesium.js"></script>\n' +
+            '    <script>window.CESIUM_BASE_URL = "../../../Build/CesiumUnminified/";</script>',
+        ),
+      )
+      .pipe(
+        gulpReplace(
+          '    <script type="module" src="load-cesium-es6.js"></script>',
+          '    <script src="../../CesiumUnminified/Cesium.js"></script>\n' +
+            '    <script>window.CESIUM_BASE_URL = "../../CesiumUnminified/";</script>',
+        ),
+      )
+      // Fix relative paths for new location
+      .pipe(gulpReplace("../../../Build", "../../.."))
+      .pipe(gulpReplace("../../Source", "../../../Source"))
+      .pipe(gulpReplace("../../ThirdParty", "../../../ThirdParty"))
+      .pipe(gulpReplace("../../SampleData", "../../../../Apps/SampleData"))
+      .pipe(gulpReplace("Build/Documentation", "Documentation"))
+      .pipe(gulp.dest("Build/Apps/Sandcastle"));
+  }
+  streams.push(appStream);
+
+  let imageStream = gulp.src(
+    ["Apps/Sandcastle/gallery/**.jpg", "Apps/Sandcastle/images/**"],
+    {
+      base: "Apps/Sandcastle",
+      encoding: false,
+    },
+  );
+  if (isProduction) {
+    imageStream = imageStream.pipe(gulp.dest("Build/Sandcastle"));
+  } else {
+    imageStream = imageStream.pipe(gulp.dest("Build/Apps/Sandcastle"));
+  }
+  streams.push(imageStream);
+
+  if (isProduction) {
+    const fileStream = gulp
+      .src(["ThirdParty/**"], { encoding: false })
+      .pipe(gulp.dest("Build/Sandcastle/ThirdParty"));
+    streams.push(fileStream);
+
+    const dataStream = gulp
+      .src(["Apps/SampleData/**"], { encoding: false })
+      .pipe(gulp.dest("Build/Sandcastle/SampleData"));
+    streams.push(dataStream);
+  }
+
+  let standaloneStream = gulp
+    .src(["Apps/Sandcastle/standalone.html"])
+    .pipe(gulpReplace("../../../", "."))
+    .pipe(
+      gulpReplace(
+        '    <script type="module" src="load-cesium-es6.js"></script>',
+        '    <script src="../CesiumUnminified/Cesium.js"></script>\n' +
+          '    <script>window.CESIUM_BASE_URL = "../CesiumUnminified/";</script>',
+      ),
+    )
+    .pipe(gulpReplace("../../Build", "."));
+  if (isProduction) {
+    standaloneStream = standaloneStream.pipe(gulp.dest("Build/Sandcastle"));
+  } else {
+    standaloneStream = standaloneStream.pipe(
+      gulp.dest("Build/Apps/Sandcastle"),
+    );
+  }
+  streams.push(standaloneStream);
+
+  return Promise.all(streams.map((s) => finished(s)));
+}
+
+async function buildCesiumViewer() {
+  const cesiumViewerOutputDirectory = isProduction
+    ? "Build/CesiumViewer"
+    : "Build/Apps/CesiumViewer";
+  mkdirp.sync(cesiumViewerOutputDirectory);
+
+  const config = defaultESBuildOptions();
+  config.entryPoints = [
+    "Apps/CesiumViewer/CesiumViewer.js",
+    "Apps/CesiumViewer/CesiumViewer.css",
+  ];
+  config.bundle = true; // Tree-shaking is enabled automatically
+  config.minify = true;
+  config.loader = {
+    ".gif": "text",
+    ".png": "text",
+  };
+  config.format = "iife";
+  // Configure Cesium base path to use built
+  config.define = { CESIUM_BASE_URL: `"."` };
+  config.outdir = cesiumViewerOutputDirectory;
+  config.outbase = "Apps/CesiumViewer";
+  config.logLevel = "error"; // print errors immediately, and collect warnings so we can filter out known ones
+  const result = await esbuild(config);
+
+  handleBuildWarnings(result);
+
+  await esbuild({
+    entryPoints: ["packages/widgets/Source/InfoBox/InfoBoxDescription.css"],
+    minify: true,
+    bundle: true,
+    loader: {
+      ".gif": "text",
+      ".png": "text",
+    },
+    outdir: join(cesiumViewerOutputDirectory, "Widgets"),
+    outbase: "packages/widgets/Source/",
+  });
+
+  await bundleWorkers({
+    minify: true,
+    removePragmas: true,
+    path: cesiumViewerOutputDirectory,
+  });
+
+  const stream = gulp
+    .src(
+      [
+        "Apps/CesiumViewer/**",
+        "!Apps/CesiumViewer/Images",
+        "!Apps/CesiumViewer/**/*.js",
+        "!Apps/CesiumViewer/**/*.css",
+      ],
+      {
+        encoding: false,
+      },
+    )
+    .pipe(
+      gulp.src(
+        [
+          "Build/Cesium/Assets/**",
+          "Build/Cesium/Workers/**",
+          "Build/Cesium/ThirdParty/**",
+          "Build/Cesium/Widgets/**",
+          "!Build/Cesium/Widgets/**/*.css",
+        ],
+        {
+          base: "Build/Cesium",
+          nodir: true,
+          encoding: false,
+        },
+      ),
+    )
+    .pipe(gulp.src(["web.config"]))
+    .pipe(gulp.dest(cesiumViewerOutputDirectory));
+
+  await finished(stream);
+  return stream;
+}
+
+export async function buildSandcastle() {
+  return buildSandcastleApp({
+    outputToBuildDir: isProduction,
+    includeDevelopment: !isProduction,
+  });
+}
+
+export const buildApps = gulp.parallel(
+  buildCesiumViewer,
+  buildLegacySandcastle,
+  buildSandcastle,
+);