fix(gatsby-adapter-netlify): handler generation on windows (#38900) (#38929)

* test: add unit test for produced handler

* actually failing test in windows

* fix(gatsby-adapter-netlify): produce working function handlers on windows

* fix(gatsby): functions compilation on windows

* tmp: prepare cross-platform binaries for SSR/DSG

* fix: lint

* feat: add a way to configure functions executing platform/arch and add early check in DSG/SSR

* refactor: move some utility functions around, cleanup standalone-regenrate, restore engine validation, add structured error and better error messages

* chore: add jsdocs description for functionsPlatform and functionsArch optional config values passed by adapter

* chore: make sure fs wrapper is first

* fix: actually use values reported by adapter

* test: try to setup windows adapters smoke test

* test: typo

* test: maybe cd into dirs?

* test: no powershell fro smoke test

* chore: single quote to double

* chore: install node-gyp requirements

* chore: install deps in win smoke

* ?

* newer node needed for ntl-cli

* run ntl through yarn

* Revert "run ntl through yarn"

This reverts commit 8c55e40.

* install ntl-cli in circleci pipeline

* test: adjust lmdb regeneration test to changed internal-packages location

* test: run windows deploy/smoke test after unit tests passed

* chore: use path.posix to load engines in serve command

* chore: use default value when destructuring instead of nullish coalescing later

(cherry picked from commit c91ed28)

Co-authored-by: Michal Piechowiak <misiek.piechowiak@gmail.com>

Author: gatsbybot

.circleci/config.yml

@@ -580,6 +580,43 @@ jobs:
       - store_test_results:
           path: ./test-results/jest-node/
 
+  windows_adapters_smoke:
+    executor:
+      name: win/default
+      shell: bash.exe
+    steps:
+      - checkout
+      - run:
+          command: ./scripts/assert-changed-files.sh "packages/*|(e2e|integration)-tests/*|.circleci/*|scripts/e2e-test.sh|yarn.lock"
+      - <<: *attach_to_bootstrap
+      - run:
+          name: Install node 18.19.0, yarn and netlify-cli
+          command: |
+            nvm install 18.19.0
+            nvm alias default 18.19.0
+            nvm use 18.19.0
+            npm install -g yarn netlify-cli
+      - run:
+          name: Clear out sharp
+          command: |
+            Remove-Item -Recurse -Force -Path "node_modules/sharp/"
+          shell: powershell.exe
+      - run:
+          command: yarn
+      - run:
+          command: mkdir -p /tmp/e2e-tests/
+      - run:
+          command: cp -r ./e2e-tests/adapters /tmp/e2e-tests/adapters
+      - run:
+          command: pwd && ls
+          working_directory: /tmp/e2e-tests/adapters
+      - run: # Set project dir
+          command: node ./packages/gatsby-dev-cli/dist/index.js --set-path-to-repo .
+      - run: # Copy over packages
+          command: cd /tmp/e2e-tests/adapters && node ~/project/packages/gatsby-dev-cli/dist/index.js --force-install --scan-once
+      - run: # run smoke test
+          command: cd /tmp/e2e-tests/adapters && node scripts/deploy-and-run/netlify.mjs test:smoke
+
 workflows:
   version: 2
 
@@ -611,6 +648,14 @@ workflows:
           requires:
             - lint
             - bootstrap
+      - windows_adapters_smoke:
+          requires:
+            # ideally we wait for windows unit tests here, but because those are flaky
+            # feedback loop would be not practical, so at least wait for linux unit tests
+            # to resemble setup for more robust E2E tests
+            - lint
+            - bootstrap
+            - unit_tests_node18
       - unit_tests_node18:
           <<: *ignore_docs
           requires:

e2e-tests/adapters/package.json

@@ -17,6 +17,7 @@
     "test:template:debug": "cross-env-shell CYPRESS_GROUP_NAME=\"adapter:$ADAPTER / trailingSlash:${TRAILING_SLASH:-always} / pathPrefix:${PATH_PREFIX:--}\" TRAILING_SLASH=$TRAILING_SLASH PATH_PREFIX=$PATH_PREFIX npm run cy:open -- --config-file \"cypress/configs/$ADAPTER.ts\" --env TRAILING_SLASH=$TRAILING_SLASH,PATH_PREFIX=$PATH_PREFIX",
     "test:debug": "npm-run-all -s build:debug ssat:debug",
     "test:netlify": "cross-env TRAILING_SLASH=always node scripts/deploy-and-run/netlify.mjs test:template",
+    "test:smoke": "node smoke-test.mjs",
     "test:netlify:debug": "cross-env TRAILING_SLASH=always node scripts/deploy-and-run/netlify.mjs test:template:debug",
     "test:netlify:prefix-never": "cross-env TRAILING_SLASH=never PATH_PREFIX=/prefix node scripts/deploy-and-run/netlify.mjs test:template",
     "test:netlify:prefix-never:debug": "cross-env TRAILING_SLASH=never PATH_PREFIX=/prefix node scripts/deploy-and-run/netlify.mjs test:template:debug",

e2e-tests/adapters/smoke-test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert"
+
+{
+  // check index page (SSG)
+  const response = await fetch(process.env.DEPLOY_URL)
+  assert.equal(response.status, 200)
+
+  const body = await response.text()
+  assert.match(body, /<h1>Adapters<\/h1>/)
+  assert.match(body, /<title[^>]*>Adapters E2E<\/title>/)
+}
+
+{
+  // check SSR page
+  const response = await fetch(
+    process.env.DEPLOY_URL + `/routes/ssr/remote-file/`
+  )
+  assert.equal(response.status, 200)
+
+  const body = await response.text()
+  // inline css for placeholder - this tests both LMDB and SHARP
+  // (LMDB because of page query and sharp because page query will use sharp to generate placeholder values)
+  assert.match(body, /background-color:rgb\(232,184,8\)/)
+}

integration-tests/lmdb-regeneration/__tests__/index.js

@@ -38,7 +38,13 @@ describe(`Lmdb regeneration`, () => {
 
     // If the fix worked correctly we should have installed the prebuilt binary for our platform under our `.cache` directory
     const lmdbRequire = mod.createRequire(
-      path.resolve(rootPath, ".cache", "internal-packages", "package.json")
+      path.resolve(
+        rootPath,
+        ".cache",
+        "internal-packages",
+        `${process.platform}-${process.arch}`,
+        "package.json"
+      )
     )
     expect(() => {
       lmdbRequire.resolve(lmdbPackage)

packages/gatsby-adapter-netlify/package.json

@@ -37,7 +37,8 @@
     "@netlify/functions": "^1.6.0",
     "cookie": "^0.5.0",
     "fastq": "^1.15.0",
-    "fs-extra": "^11.1.1"
+    "fs-extra": "^11.1.1",
+    "gatsby-core-utils": "^4.13.1"
   },
   "devDependencies": {
     "@babel/cli": "^7.20.7",

packages/gatsby-adapter-netlify/src/__tests__/fixtures/lambda-handler/entry.js

@@ -0,0 +1,46 @@
+import fs from "fs-extra"
+import { prepareFunction } from "../lambda-handler"
+import { join, relative } from "path"
+import { slash } from "gatsby-core-utils/path"
+
+const writeFileSpy = jest
+  .spyOn(fs, `writeFile`)
+  .mockImplementation(async () => {})
+const writeJsonSpy = jest
+  .spyOn(fs, `writeJSON`)
+  .mockImplementation(async () => {})
+
+const fixturePath = join(
+  relative(process.cwd(), __dirname),
+  `fixtures`,
+  `lambda-handler`
+)
+const pathToEntryPoint = join(fixturePath, `entry.js`)
+const requiredFile = join(fixturePath, `included.js`)
+
+test(`produced handler is correct`, async () => {
+  await prepareFunction({
+    functionId: `test`,
+    name: `test`,
+    pathToEntryPoint,
+    requiredFiles: [requiredFile],
+  })
+  const handlerCode = writeFileSpy.mock.calls[0][1]
+  // expect require in produced code (this is to mostly to make sure handlerCode is actual handler code)
+  expect(handlerCode).toMatch(/require\(["'][^"']*["']\)/)
+  // require paths should not have backward slashes (win paths)
+  expect(handlerCode).not.toMatch(/require\(["'][^"']*\\[^"']*["']\)/)
+
+  expect(writeJsonSpy).toBeCalledWith(
+    expect.any(String),
+    expect.objectContaining({
+      config: expect.objectContaining({
+        name: `test`,
+        generator: expect.stringContaining(`gatsby-adapter-netlify`),
+        includedFiles: [slash(requiredFile)],
+        externalNodeModules: [`msgpackr-extract`],
+      }),
+      version: 1,
+    })
+  )
+})

packages/gatsby-adapter-netlify/src/__tests__/fixtures/lambda-handler/included.js

@@ -162,6 +162,8 @@ const createNetlifyAdapter: AdapterInit<INetlifyAdapterOptions> = options => {
         fileCDNUrlGeneratorModulePath: useNetlifyImageCDN
           ? require.resolve(`./file-cdn-url-generator`)
           : undefined,
+        functionsPlatform: `linux`,
+        functionsArch: `x64`,
       }
     },
   }

packages/gatsby-adapter-netlify/src/__tests__/lambda-handler.ts

@@ -2,6 +2,7 @@ import type { IFunctionDefinition } from "gatsby"
 import packageJson from "gatsby-adapter-netlify/package.json"
 import fs from "fs-extra"
 import * as path from "path"
+import { slash } from "gatsby-core-utils/path"
 
 interface INetlifyFunctionConfig {
   externalNodeModules?: Array<string>
@@ -25,7 +26,7 @@ interface INetlifyFunctionManifest {
   version: number
 }
 
-async function prepareFunction(
+export async function prepareFunction(
   fun: IFunctionDefinition,
   odbfunctionName?: string
 ): Promise<void> {
@@ -58,7 +59,7 @@ async function prepareFunction(
       name: displayName,
       generator: `gatsby-adapter-netlify@${packageJson?.version ?? `unknown`}`,
       includedFiles: fun.requiredFiles.map(file =>
-        file.replace(/\[/g, `*`).replace(/]/g, `*`)
+        slash(file).replace(/\[/g, `*`).replace(/]/g, `*`)
       ),
       externalNodeModules: [`msgpackr-extract`],
     },
@@ -73,7 +74,10 @@ async function prepareFunction(
   function getRelativePathToModule(modulePath: string): string {
     const absolutePath = require.resolve(modulePath)
 
-    return `./` + path.relative(internalFunctionsDir, absolutePath)
+    return (
+      `./` +
+      path.posix.relative(slash(internalFunctionsDir), slash(absolutePath))
+    )
   }
 
   const handlerSource = /* javascript */ `

packages/gatsby-adapter-netlify/src/index.ts

@@ -273,6 +273,14 @@ function buildLocalCommands(cli: yargs.Argv, isLocalSite: boolean): void {
           default: false,
           describe: `Save the log of changed pages for future comparison.`,
           hidden: true,
+        })
+        .option(`functions-platform`, {
+          type: `string`,
+          describe: `The platform bundled functions will execute on. Defaults to current platform or settings provided by used adapter.`,
+        })
+        .option(`functions-arch`, {
+          type: `string`,
+          describe: `The architecture bundled functions will execute on. Defaults to current architecture or settings provided by used adapter.`,
         }),
     handler: handlerP(
       getCommandHandler(

packages/gatsby-adapter-netlify/src/lambda-handler.ts

@@ -83,6 +83,12 @@ const errors: Record<string, IErrorMapEntry> = {
     level: Level.ERROR,
     category: ErrorCategory.USER,
   },
+  "98051": {
+    text: (): string => `Built Rendering Engines failed to load.`,
+    type: Type.ENGINE_EXECUTION,
+    level: Level.ERROR,
+    category: ErrorCategory.UNKNOWN,
+  },
   "98123": {
     text: (context): string =>
       `${context.stageLabel} failed\n\n${

packages/gatsby-cli/src/create-cli.ts

@@ -16,7 +16,7 @@
   "license": "MIT",
   "scripts": {
     "build": "npm-run-all --npm-path npm -p build:*",
-    "build:exclude": "cpy 'exclude.js' '../dist' --cwd=./src",
+    "build:exclude": "cpy \"exclude.js\" \"../dist\" --cwd=./src",
     "build:polyfills": "microbundle -f iife -i src/polyfills.js --no-sourcemap --external=none",
     "prepare": "cross-env NODE_ENV=production npm run build",
     "watch": "npm-run-all --npm-path npm -p watch:*",

packages/gatsby-cli/src/structured-errors/error-map.ts

@@ -47,7 +47,7 @@
   "scripts": {
     "build": "npm run build:src && npm run build:sw-append",
     "build:src": "babel src --out-dir . --ignore \"**/__tests__,src/sw-append.js\"",
-    "build:sw-append": "cpy 'sw-append.js' '../' --cwd=./src",
+    "build:sw-append": "cpy \"sw-append.js\" \"../\" --cwd=./src",
     "prepare": "cross-env NODE_ENV=production npm run build",
     "watch": "npm run build:sw-append -- --watch & npm run build:src -- --watch"
   },

packages/gatsby-legacy-polyfills/package.json

@@ -42,6 +42,8 @@ export interface IBuildArgs extends IProgram {
   profile: boolean
   graphqlTracing: boolean
   openTracingConfigFile: string
+  functionsPlatform?: string
+  functionsArch?: string
   // TODO remove in v4
   keepPageRenderer: boolean
 }

packages/gatsby-plugin-offline/package.json

@@ -66,7 +66,7 @@ import {
   getPageMode,
   preparePageTemplateConfigs,
 } from "../utils/page-mode"
-import { validateEngines } from "../utils/validate-engines"
+import { validateEnginesWithActivity } from "../utils/validate-engines"
 import { constructConfigObject } from "../utils/gatsby-cloud-config"
 import { waitUntilWorkerJobsAreComplete } from "../utils/jobs/worker-messaging"
 import { getSSRChunkHashes } from "../utils/webpack/get-ssr-chunk-hashes"
@@ -295,20 +295,7 @@ module.exports = async function build(
   }
 
   if (shouldGenerateEngines()) {
-    const validateEnginesActivity = report.activityTimer(
-      `Validating Rendering Engines`,
-      {
-        parentSpan: buildSpan,
-      }
-    )
-    validateEnginesActivity.start()
-    try {
-      await validateEngines(store.getState().program.directory)
-    } catch (error) {
-      validateEnginesActivity.panic({ id: `98001`, context: {}, error })
-    } finally {
-      validateEnginesActivity.end()
-    }
+    await validateEnginesWithActivity(program.directory, buildSpan)
   }
 
   const cacheActivity = report.activityTimer(`Caching Webpack compilations`, {

packages/gatsby/src/commands/build-html.ts

@@ -29,6 +29,7 @@ import {
   thirdPartyProxyPath,
   partytownProxy,
 } from "../internal-plugins/partytown/proxy"
+import { slash } from "gatsby-core-utils/path"
 
 interface IMatchPath {
   path: string
@@ -184,125 +185,146 @@ module.exports = async (program: IServeProgram): Promise<void> => {
   }
 
   // Handle SSR & DSG Pages
+  let graphqlEnginePath: string | undefined
+  let pageSSRModule: string | undefined
   try {
-    const { GraphQLEngine } = require(path.join(
-      program.directory,
-      `.cache`,
-      `query-engine`
-    )) as typeof import("../schema/graphql-engine/entry")
-    const { getData, renderPageData, renderHTML } = require(path.join(
-      program.directory,
-      `.cache`,
-      `page-ssr`
-    )) as typeof import("../utils/page-ssr-module/entry")
-    const graphqlEngine = new GraphQLEngine({
-      dbPath: path.join(program.directory, `.cache`, `data`, `datastore`),
-    })
+    graphqlEnginePath = require.resolve(
+      path.posix.join(slash(program.directory), `.cache`, `query-engine`)
+    )
+    pageSSRModule = require.resolve(
+      path.posix.join(slash(program.directory), `.cache`, `page-ssr`)
+    )
+  } catch (error) {
+    // TODO: Handle case of engine not being generated
+  }
 
-    router.get(
-      `/page-data/:pagePath(*)/page-data.json`,
-      async (req, res, next) => {
-        const requestedPagePath = req.params.pagePath
-        if (!requestedPagePath) {
-          return void next()
-        }
+  if (graphqlEnginePath && pageSSRModule) {
+    try {
+      const { GraphQLEngine } =
+        require(graphqlEnginePath) as typeof import("../schema/graphql-engine/entry")
+      const { getData, renderPageData, renderHTML } =
+        require(pageSSRModule) as typeof import("../utils/page-ssr-module/entry")
+      const graphqlEngine = new GraphQLEngine({
+        dbPath: path.posix.join(
+          slash(program.directory),
+          `.cache`,
+          `data`,
+          `datastore`
+        ),
+      })
+
+      router.get(
+        `/page-data/:pagePath(*)/page-data.json`,
+        async (req, res, next) => {
+          const requestedPagePath = req.params.pagePath
+          if (!requestedPagePath) {
+            return void next()
+          }
+
+          const potentialPagePath = reverseFixedPagePath(requestedPagePath)
+          const page = graphqlEngine.findPageByPath(potentialPagePath)
 
-        const potentialPagePath = reverseFixedPagePath(requestedPagePath)
-        const page = graphqlEngine.findPageByPath(potentialPagePath)
-
-        if (page && (page.mode === `DSG` || page.mode === `SSR`)) {
-          const requestActivity = report.phantomActivity(
-            `request for "${req.path}"`
-          )
-          requestActivity.start()
-          try {
-            const spanContext = requestActivity.span.context()
-            const data = await getData({
-              pathName: req.path,
-              graphqlEngine,
-              req,
-              spanContext,
-            })
-            const results = await renderPageData({ data, spanContext })
-            if (data.serverDataHeaders) {
-              for (const [name, value] of Object.entries(
-                data.serverDataHeaders
-              )) {
-                res.setHeader(name, value)
+          if (page && (page.mode === `DSG` || page.mode === `SSR`)) {
+            const requestActivity = report.phantomActivity(
+              `request for "${req.path}"`
+            )
+            requestActivity.start()
+            try {
+              const spanContext = requestActivity.span.context()
+              const data = await getData({
+                pathName: req.path,
+                graphqlEngine,
+                req,
+                spanContext,
+              })
+              const results = await renderPageData({ data, spanContext })
+              if (data.serverDataHeaders) {
+                for (const [name, value] of Object.entries(
+                  data.serverDataHeaders
+                )) {
+                  res.setHeader(name, value)
+                }
               }
-            }
 
-            if (page.mode === `SSR` && data.serverDataStatus) {
-              return void res.status(data.serverDataStatus).send(results)
-            } else {
-              return void res.send(results)
+              if (page.mode === `SSR` && data.serverDataStatus) {
+                return void res.status(data.serverDataStatus).send(results)
+              } else {
+                return void res.send(results)
+              }
+            } catch (e) {
+              report.error(
+                `Generating page-data for "${requestedPagePath}" / "${potentialPagePath}" failed.`,
+                e
+              )
+              return res
+                .status(500)
+                .contentType(`text/plain`)
+                .send(`Internal server error.`)
+            } finally {
+              requestActivity.end()
             }
-          } catch (e) {
-            report.error(
-              `Generating page-data for "${requestedPagePath}" / "${potentialPagePath}" failed.`,
-              e
-            )
-            return res
-              .status(500)
-              .contentType(`text/plain`)
-              .send(`Internal server error.`)
-          } finally {
-            requestActivity.end()
           }
-        }
 
-        return void next()
-      }
-    )
+          return void next()
+        }
+      )
 
-    router.use(async (req, res, next) => {
-      if (req.accepts(`html`)) {
-        const potentialPagePath = req.path
-        const page = graphqlEngine.findPageByPath(potentialPagePath)
-        if (page && (page.mode === `DSG` || page.mode === `SSR`)) {
-          const requestActivity = report.phantomActivity(
-            `request for "${req.path}"`
-          )
-          requestActivity.start()
-
-          try {
-            const spanContext = requestActivity.span.context()
-            const data = await getData({
-              pathName: potentialPagePath,
-              graphqlEngine,
-              req,
-              spanContext,
-            })
-            const results = await renderHTML({ data, spanContext })
-            if (data.serverDataHeaders) {
-              for (const [name, value] of Object.entries(
-                data.serverDataHeaders
-              )) {
-                res.setHeader(name, value)
+      router.use(async (req, res, next) => {
+        if (req.accepts(`html`)) {
+          const potentialPagePath = req.path
+          const page = graphqlEngine.findPageByPath(potentialPagePath)
+          if (page && (page.mode === `DSG` || page.mode === `SSR`)) {
+            const requestActivity = report.phantomActivity(
+              `request for "${req.path}"`
+            )
+            requestActivity.start()
+
+            try {
+              const spanContext = requestActivity.span.context()
+              const data = await getData({
+                pathName: potentialPagePath,
+                graphqlEngine,
+                req,
+                spanContext,
+              })
+              const results = await renderHTML({ data, spanContext })
+              if (data.serverDataHeaders) {
+                for (const [name, value] of Object.entries(
+                  data.serverDataHeaders
+                )) {
+                  res.setHeader(name, value)
+                }
               }
-            }
 
-            if (page.mode === `SSR` && data.serverDataStatus) {
-              return void res.status(data.serverDataStatus).send(results)
-            } else {
-              return void res.send(results)
-            }
-          } catch (e) {
-            report.error(`Rendering html for "${potentialPagePath}" failed.`, e)
-            return res.status(500).sendFile(`500.html`, { root }, err => {
-              if (err) {
-                res.contentType(`text/plain`).send(`Internal server error.`)
+              if (page.mode === `SSR` && data.serverDataStatus) {
+                return void res.status(data.serverDataStatus).send(results)
+              } else {
+                return void res.send(results)
               }
-            })
-          } finally {
-            requestActivity.end()
+            } catch (e) {
+              report.error(
+                `Rendering html for "${potentialPagePath}" failed.`,
+                e
+              )
+              return res.status(500).sendFile(`500.html`, { root }, err => {
+                if (err) {
+                  res.contentType(`text/plain`).send(`Internal server error.`)
+                }
+              })
+            } finally {
+              requestActivity.end()
+            }
           }
         }
-      }
-      return next()
-    })
-  } catch (error) {
-    // TODO: Handle case of engine not being generated
+        return next()
+      })
+    } catch (error) {
+      report.panic({
+        id: `98051`,
+        error,
+        context: {},
+      })
+    }
   }
 
   const matchPaths = await readMatchPaths(program)

packages/gatsby/src/commands/build.ts

@@ -34,6 +34,8 @@ export interface IProgram {
   graphqlTracing?: boolean
   verbose?: boolean
   prefixPaths?: boolean
+  functionsPlatform?: string
+  functionsArch?: string
   setStore?: (store: Store<IGatsbyState, AnyAction>) => void
   disablePlugins?: Array<{
     name: string

packages/gatsby/src/commands/serve.ts

@@ -10,17 +10,17 @@ const APIFunctionLoader: LoaderDefinition = async function () {
   return /* javascript */ `
   const preferDefault = m => (m && m.default) || m
 
-  const functionModule = require('${modulePath}');
+  const functionModule = require('${slash(modulePath)}');
   const functionToExecute = preferDefault(functionModule);
   const matchPath = '${matchPath}';
-  const { match: reachMatch } = require('${require.resolve(
-    `@gatsbyjs/reach-router`
+  const { match: reachMatch } = require('${slash(
+    require.resolve(`@gatsbyjs/reach-router`)
   )}');
-  const { urlencoded, text, json, raw } = require('${require.resolve(
-    `body-parser`
+  const { urlencoded, text, json, raw } = require('${slash(
+    require.resolve(`body-parser`)
   )}')
-  const multer = require('${require.resolve(`multer`)}')
-  const { createConfig } = require('${require.resolve(`./config`)}')
+  const multer = require('${slash(require.resolve(`multer`))}')
+  const { createConfig } = require('${slash(require.resolve(`./config`))}')
 
   function functionWrapper(req, res) {
     if (matchPath) {

packages/gatsby/src/commands/types.ts

@@ -1,6 +1,7 @@
 // "engines-fs-provider" must be first import, as it sets up global
 // fs and this need to happen before anything else tries to import fs
 import "../../utils/engines-fs-provider"
+import "./platform-and-arch-check"
 
 import { getCache as getGatsbyCache } from "../../utils/get-cache"
 

packages/gatsby/src/internal-plugins/functions/api-function-webpack-loader.ts

@@ -0,0 +1,12 @@
+if (
+  process.env.GATSBY_FUNCTIONS_PLATFORM !== process.platform ||
+  process.env.GATSBY_FUNCTIONS_ARCH !== process.arch
+) {
+  throw new Error(
+    `Incompatible DSG/SSR executing environment. Function was built for "${process.env.GATSBY_FUNCTIONS_PLATFORM}/${process.env.GATSBY_FUNCTIONS_ARCH}" but is executing on "${process.platform}/${process.arch}".` +
+      (process.env.gatsby_executing_command === `serve`
+        ? `\n\nIf you are trying to run DSG/SSR engine locally, consider using experimental utility to rebuild functions for your local platform:\n\nnode node_modules/gatsby/dist/schema/graphql-engine/standalone-regenerate.js`
+        : ``) +
+      `\n\nTo generate engines for "${process.platform}/${process.arch}" run 'gatsby build --functions-platform=${process.platform} --functions-arch=${process.arch}' or run 'gatsby build' with following envirnment variables:\n\nGATSBY_FUNCTIONS_PLATFORM=${process.platform}\nGATSBY_FUNCTIONS_ARCH=${process.arch}`
+  )
+}

packages/gatsby/src/schema/graphql-engine/bootstrap.ts

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 
 /*
-this is used for development purposes only
-to be able to run `gatsby build` once to source data
-and print schema and then just rebundle graphql-engine
+This is used mostly for development purposes, but can be attempted to be used
+to regenerate just engines for local platform/arch if previous full build
+was done to deploy on platform with different arch/platform.
+
+For development purposes this is used to be able to run `gatsby build` once to
+source data and print schema and then just rebundle graphql-engine
 with source file changes and test re-built engine quickly
 
 Usage:
 There need to be at least one successful `gatsby build`
 before starting to use this script (warm up datastore,
 generate "page-ssr" bundle). Once that's done you can
-run following command in test site directory:
+run following command in site directory:
 
 ```shell
 node node_modules/gatsby/dist/schema/graphql-engine/standalone-regenerate.js
@@ -23,18 +26,18 @@ import reporter from "gatsby-cli/lib/reporter"
 import { loadConfigAndPlugins } from "../../utils/worker/child/load-config-and-plugins"
 import * as fs from "fs-extra"
 import { store } from "../../redux"
-import { validateEngines } from "../../utils/validate-engines"
+import { validateEnginesWithActivity } from "../../utils/validate-engines"
 
 async function run(): Promise<void> {
   process.env.GATSBY_SLICES = `1`
   // load config
-  console.log(`loading config and plugins`)
+  reporter.verbose(`loading config and plugins`)
   await loadConfigAndPlugins({
     siteDirectory: process.cwd(),
   })
 
   try {
-    console.log(`clearing webpack cache\n\n`)
+    reporter.verbose(`clearing webpack cache`)
     // get rid of cache if it exist
     await fs.remove(process.cwd() + `/.cache/webpack/query-engine`)
     await fs.remove(process.cwd() + `/.cache/webpack/page-ssr`)
@@ -46,7 +49,7 @@ async function run(): Promise<void> {
 
   // recompile
   const buildActivityTimer = reporter.activityTimer(
-    `Building Rendering Engines`
+    `(Re)Building Rendering Engines`
   )
   try {
     buildActivityTimer.start()
@@ -67,20 +70,9 @@ async function run(): Promise<void> {
     buildActivityTimer.end()
   }
 
-  // validate
-  const validateEnginesActivity = reporter.activityTimer(
-    `Validating Rendering Engines`
-  )
-  validateEnginesActivity.start()
-  try {
-    await validateEngines(process.cwd())
-  } catch (error) {
-    validateEnginesActivity.panic({ id: `98001`, context: {}, error })
-  } finally {
-    validateEnginesActivity.end()
-  }
+  await validateEnginesWithActivity(process.cwd())
 
-  console.log(`DONE`)
+  reporter.info(`Rebuilding Rendering Engines finished`)
 }
 
 run()

packages/gatsby/src/schema/graphql-engine/bundle-webpack.ts

@@ -9,6 +9,7 @@ import { satisfies } from "semver"
 import type { AdapterInit } from "./types"
 import { preferDefault } from "../../bootstrap/prefer-default"
 import { getLatestAdapters } from "../get-latest-gatsby-files"
+import { maybeAddFileProtocol } from "../../bootstrap/resolve-js-file-path"
 
 export const getAdaptersCacheDir = (): string =>
   join(process.cwd(), `.cache/adapters`)
@@ -85,7 +86,9 @@ const tryLoadingAlreadyInstalledAdapter = async ({
       }
     }
 
-    const required = locationRequire.resolve(adapterToUse.module)
+    const required = maybeAddFileProtocol(
+      locationRequire.resolve(adapterToUse.module)
+    )
     if (required) {
       return {
         found: true,

packages/gatsby/src/schema/graphql-engine/platform-and-arch-check.ts

@@ -286,6 +286,8 @@ export async function initAdapterManager(): Promise<IAdapterManager> {
         deployURL: configFromAdapter?.deployURL,
         supports: configFromAdapter?.supports,
         pluginsToDisable: configFromAdapter?.pluginsToDisable ?? [],
+        functionsArch: configFromAdapter?.functionsArch,
+        functionsPlatform: configFromAdapter?.functionsPlatform,
       }
     },
   }

packages/gatsby/src/schema/graphql-engine/standalone-regenerate.ts

@@ -201,6 +201,18 @@ export interface IAdapterConfig {
    * example for the Netlify adapter.
    */
   fileCDNUrlGeneratorModulePath?: string
+  /**
+   * The platform bundled functions will execute on. Usually should be `linux`.
+   * This will be used if user didn't specify `GATSBY_FUNCTIONS_PLATFORM` environment variable
+   * or used `-functions-platform` CLI toggle. If none is defined current platform (process.platform) will be used.
+   */
+  functionsPlatform?: string
+  /**
+   * The architecture bundled functions will execute on. Usually should be `x64`.
+   * This will be used if user didn't specify `GATSBY_FUNCTIONS_ARCH` environment variable
+   * or used `-functions-arch` CLI toggle. If none is defined current arch (process.arch) will be used.
+   */
+  functionsArch?: string
 }
 
 type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] }

packages/gatsby/src/utils/adapter/init.ts

@@ -33,3 +33,34 @@ function getCDNObfuscatedPath(path: string): string {
 }
 
 export const LmdbOnCdnPath = getCDNObfuscatedPath(`data.mdb`)
+
+export interface IPlatformAndArch {
+  platform: string
+  arch: string
+}
+
+const currentTarget: IPlatformAndArch = {
+  platform: process.platform,
+  arch: process.arch,
+}
+
+export function getCurrentPlatformAndTarget(): IPlatformAndArch {
+  return currentTarget
+}
+
+export function getFunctionsTargetPlatformAndTarget(): IPlatformAndArch {
+  const state = store.getState()
+
+  return {
+    platform:
+      process.env.GATSBY_FUNCTIONS_PLATFORM ??
+      state.program.functionsPlatform ??
+      state.adapter.config.functionsPlatform ??
+      currentTarget.platform,
+    arch:
+      process.env.GATSBY_FUNCTIONS_ARCH ??
+      state.program.functionsArch ??
+      state.adapter.config.functionsArch ??
+      currentTarget.arch,
+  }
+}

packages/gatsby/src/utils/adapter/manager.ts

@@ -1,6 +1,45 @@
+import reporter from "gatsby-cli/lib/reporter"
 import { WorkerPool } from "gatsby-worker"
+import { isEqual } from "lodash"
+import type { Span } from "opentracing"
+import {
+  getCurrentPlatformAndTarget,
+  getFunctionsTargetPlatformAndTarget,
+} from "../engines-helpers"
 
-export async function validateEngines(directory: string): Promise<void> {
+export async function validateEnginesWithActivity(
+  directory: string,
+  buildSpan?: Span
+): Promise<void> {
+  if (
+    !isEqual(
+      getCurrentPlatformAndTarget(),
+      getFunctionsTargetPlatformAndTarget()
+    )
+  ) {
+    reporter.info(
+      `Skipping Rendering Engines validation as they are build for different platform and/or architecture`
+    )
+    return
+  }
+
+  const validateEnginesActivity = reporter.activityTimer(
+    `Validating Rendering Engines`,
+    {
+      parentSpan: buildSpan,
+    }
+  )
+  validateEnginesActivity.start()
+  try {
+    await validateEngines(directory)
+  } catch (error) {
+    validateEnginesActivity.panic({ id: `98001`, context: {}, error })
+  } finally {
+    validateEnginesActivity.end()
+  }
+}
+
+async function validateEngines(directory: string): Promise<void> {
   const worker = new WorkerPool<typeof import("./child")>(
     require.resolve(`./child`),
     {