reset-framework-cli 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reset-framework-cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "description": "Command-line tooling for Reset Framework.",
   "license": "MIT",
@@ -11,13 +11,15 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
-    "@reset-framework/schema": "1.2.1",
-    "@reset-framework/sdk": "1.2.1"
+    "@reset-framework/backend": "1.2.2",
+    "@reset-framework/schema": "1.2.2",
+    "@reset-framework/sdk": "1.2.2",
+    "esbuild": "^0.25.10"
   },
   "optionalDependencies": {
-    "@reset-framework/runtime-darwin-arm64": "1.2.1",
-    "@reset-framework/runtime-darwin-x64": "1.2.1",
-    "@reset-framework/runtime-win32-x64": "1.2.1"
+    "@reset-framework/runtime-darwin-arm64": "1.2.2",
+    "@reset-framework/runtime-darwin-x64": "1.2.2",
+    "@reset-framework/runtime-win32-x64": "1.2.2"
   },
   "bin": {
     "reset-framework-cli": "src/index.js"

package/src/commands/build.js

@@ -1,4 +1,5 @@
 import { prepareFrameworkRuntime } from "../lib/framework.js"
+import { prepareAppBackend } from "../lib/backend.js"
 import { stageMacOSAppBundle, stageWindowsAppBundle } from "../lib/output.js"
 import { resolvePackageManagerCommand, runCommand } from "../lib/process.js"
 import {
@@ -12,7 +13,8 @@ import {
   resolveFrontendDir,
   resolveFrameworkBuildPaths,
   resolveFrameworkRuntimeStrategy,
-  resolveFrameworkPaths
+  resolveFrameworkPaths,
+  resolveOptionalBackendEntry
 } from "../lib/project.js"
 import {
   createProgress,
@@ -41,11 +43,13 @@ export async function run(context) {
   const outputPaths = resolveAppOutputPaths(appPaths, config)
   const configPath = resolveConfigPath(appPaths)
   const frontendDir = resolveFrontendDir(appPaths, config)
+  const backendEntry = resolveOptionalBackendEntry(appPaths)
   const frameworkBuildPaths = resolveFrameworkBuildPaths(appPaths)
   const runtimeStrategy = resolveFrameworkRuntimeStrategy(frameworkPaths, { preferSource })
   const steps = [
     !skipFrontend ? "Build frontend" : null,
     !skipRuntime ? "Prepare runtime" : null,
+    !skipStage && backendEntry ? "Bundle backend sidecar" : null,
     !skipStage ? "Stage desktop bundle" : null
   ].filter(Boolean)
 
@@ -54,6 +58,7 @@ export async function run(context) {
   printKeyValueTable([
     ["Config", configPath],
     ["Frontend", frontendDir],
+    ["Backend", backendEntry ?? "not configured"],
     ["Package manager", packageManager],
     ["Output", outputPaths.appBundlePath],
     ["Runtime", `${runtimeStrategy.kind === "prebuilt" ? "bundled" : "source"} (${runtimeStrategy.label})`]
@@ -70,6 +75,11 @@ export async function run(context) {
         ? (runtimeStrategy.kind === "prebuilt" ? "Reuse the bundled runtime package" : "Skip the source runtime build")
         : (runtimeStrategy.kind === "prebuilt" ? "Use the bundled runtime package" : "Configure and build the runtime from source")
     ],
+    [
+      backendEntry && !skipStage ? "ready" : "skip",
+      "Backend",
+      backendEntry && !skipStage ? "Bundle the optional TypeScript sidecar backend" : "No backend staging is required"
+    ],
     [skipStage ? "skip" : "ready", "Bundle", skipStage ? "Skipping app bundle staging" : "Assemble the final desktop app bundle"]
   ])
 
@@ -94,6 +104,8 @@ export async function run(context) {
   console.log("")
   const progress = createProgress(steps.length, "Build")
 
+  let backendArtifact = null
+
   if (!skipFrontend) {
     await runCommand(resolvePackageManagerCommand(packageManager), ["run", "build"], {
       cwd: frontendDir,
@@ -111,13 +123,19 @@ export async function run(context) {
     progress.tick(preparedRuntime.kind === "prebuilt" ? "Bundled runtime ready" : "Native runtime built")
   }
 
+  if (!skipStage && backendEntry) {
+    backendArtifact = await prepareAppBackend(frameworkPaths, appPaths, "release")
+    progress.tick("Backend sidecar bundled")
+  }
+
   if (!skipStage) {
     const stageBundle = process.platform === "win32" ? stageWindowsAppBundle : stageMacOSAppBundle
     await stageBundle(frameworkPaths, frameworkBuildPaths, config, {
       dryRun,
       outputPaths,
       configPath,
-      preferSource
+      preferSource,
+      backendArtifact
     })
     progress.tick("Desktop app bundle staged")
   }

package/src/commands/dev.js

@@ -1,4 +1,5 @@
 import { prepareFrameworkRuntime } from "../lib/framework.js"
+import { prepareAppBackend } from "../lib/backend.js"
 import {
   registerChildCleanup,
   resolvePackageManagerCommand,
@@ -18,7 +19,8 @@ import {
   resolveFrameworkBuildPaths,
   resolveFrameworkRuntimeBinary,
   resolveFrameworkRuntimeStrategy,
-  resolveFrameworkPaths
+  resolveFrameworkPaths,
+  resolveOptionalBackendEntry
 } from "../lib/project.js"
 import {
   createProgress,
@@ -47,10 +49,12 @@ export async function run(context) {
   const devServer = resolveDevServerOptions(config)
   const configPath = resolveConfigPath(appPaths)
   const frontendDir = resolveFrontendDir(appPaths, config)
+  const backendEntry = resolveOptionalBackendEntry(appPaths)
   const frameworkBuildPaths = resolveFrameworkBuildPaths(appPaths)
   const runtimeStrategy = resolveFrameworkRuntimeStrategy(frameworkPaths, { preferSource })
   const steps = [
     !skipRuntime ? "Prepare runtime" : null,
+    backendEntry ? "Bundle backend sidecar" : null,
     !skipFrontend ? "Start frontend dev server" : null,
     !noOpen ? "Launch desktop window" : null
   ].filter(Boolean)
@@ -60,6 +64,7 @@ export async function run(context) {
   printKeyValueTable([
     ["Config", configPath],
     ["Frontend", frontendDir],
+    ["Backend", backendEntry ?? "not configured"],
     ["Package manager", packageManager],
     ["Dev URL", config.frontend.devUrl],
     ["Runtime", `${runtimeStrategy.kind === "prebuilt" ? "bundled" : "source"} (${runtimeStrategy.label})`]
@@ -75,6 +80,7 @@ export async function run(context) {
         ? (runtimeStrategy.kind === "prebuilt" ? "Reuse the bundled runtime package" : "Reuse the existing source runtime build")
         : (runtimeStrategy.kind === "prebuilt" ? "Use the bundled runtime package" : "Configure and build the runtime from source")
     ],
+    [backendEntry ? "ready" : "skip", "Backend", backendEntry ? "Bundle the optional TypeScript sidecar backend" : "No backend entry was found under backend/"],
     [skipFrontend ? "skip" : "ready", "Frontend", skipFrontend ? "Expecting an already running dev server" : "Start the frontend dev server and wait for readiness"],
     [noOpen ? "skip" : "ready", "Window", noOpen ? "Do not launch the desktop window" : "Start the native host with the active project config"]
   ])
@@ -110,6 +116,12 @@ export async function run(context) {
   }
 
   const children = []
+  let backendArtifact = null
+
+  if (backendEntry) {
+    backendArtifact = await prepareAppBackend(frameworkPaths, appPaths, "dev")
+    progress.tick("Backend sidecar bundled")
+  }
 
   if (!skipFrontend) {
     const frontendProcess = spawnCommand(resolvePackageManagerCommand(packageManager), [
@@ -142,7 +154,15 @@ export async function run(context) {
       cwd: appPaths.appRoot,
       env: {
         RESET_CONFIG_PATH: configPath,
-        RESET_FRONTEND_DEV_URL: config.frontend.devUrl
+        RESET_FRONTEND_DEV_URL: config.frontend.devUrl,
+        ...(backendArtifact
+          ? {
+              RESET_BACKEND_EXECUTABLE: backendArtifact.runtimeExecutablePath,
+              RESET_BACKEND_RUNNER: backendArtifact.runnerPath,
+              RESET_BACKEND_ENTRY: backendArtifact.bundleEntryPath,
+              RESET_BACKEND_WORKING_DIRECTORY: backendArtifact.workingDirectory
+            }
+          : {})
       },
       dryRun
     })
@@ -161,7 +181,8 @@ export async function run(context) {
   printSection("Runtime")
   printStatusTable([
     ["done", "Frontend", config.frontend.devUrl],
-    ["done", "Config", configPath]
+    ["done", "Config", configPath],
+    ["done", "Backend", backendArtifact ? backendArtifact.bundleEntryPath : "disabled"]
   ])
   console.log("  Press Ctrl+C to stop")
 

package/src/commands/doctor.js

@@ -7,6 +7,7 @@ import {
   getFrameworkRuntimeModeSummary,
   hasFrameworkSourcePackage,
   loadResetConfig,
+  resolveOptionalBackendEntry,
   resolveFrontendDir,
   resolveAppPaths,
   resolveConfigPath,
@@ -48,6 +49,10 @@ export async function run(context) {
   if (config) {
     appChecks.unshift(["frontend", resolveFrontendDir(appPaths, config)])
   }
+  const backendEntry = resolveOptionalBackendEntry(appPaths)
+  if (backendEntry) {
+    appChecks.splice(1, 0, ["backend", backendEntry])
+  }
 
   printStatusTable(
     appChecks.map(([label, filePath]) => [
@@ -97,6 +102,7 @@ export async function run(context) {
         ? `${frameworkPaths.frameworkPackage.packageName}@${frameworkPaths.frameworkPackage.version}`
         : "Not installed"
     ],
+    ["Backend", `${frameworkPaths.backendPackage.packageName}@${frameworkPaths.backendPackage.version}`],
     ["SDK", `${frameworkPaths.sdkPackage.packageName}@${frameworkPaths.sdkPackage.version}`],
     ["Schema", `${frameworkPaths.schemaPackage.packageName}@${frameworkPaths.schemaPackage.version}`]
   ])
@@ -129,6 +135,7 @@ export async function run(context) {
       ["Product", config.productName],
       ["App ID", config.appId],
       ["Frontend", config.project.frontendDir],
+      ["Backend", backendEntry ?? "disabled"],
       ["Styling", config.project.styling],
       ["Dev URL", config.frontend.devUrl],
       ["Output", config.build.outputDir]

package/src/commands/init.js

@@ -10,6 +10,7 @@ import {
 } from "../lib/process.js"
 import {
   makeAppMetadata,
+  resolveBackendDependencySpec,
   resolveCliDependencySpec,
   resolveFrameworkPaths,
   resolveSdkDependencySpec
@@ -30,6 +31,40 @@ import {
 const sdkRuntimeReexport = `export * from '@reset-framework/sdk'
 `
 
+const backendTsconfig = `{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`
+
+const backendStarterSource = `import { defineBackend } from '@reset-framework/backend'
+
+export default defineBackend(({ handle, process }) => {
+  handle('backend.ping', async () => {
+    return {
+      ok: true,
+      runtime: globalThis.process.release?.name ?? 'node',
+      version: globalThis.process.version
+    }
+  })
+
+  handle('backend.execVersion', async () => {
+    return process.run({
+      command: globalThis.process.execPath,
+      args: ['--version']
+    })
+  })
+})
+`
+
 const standaloneViteConfig = `import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
@@ -431,7 +466,7 @@ function createRootPackageJson(options) {
   }
 
   if (options.frontendDir !== ".") {
-    base.workspaces = [options.frontendDir]
+    base.workspaces = [options.frontendDir, "backend"]
     base.scripts["dev:web"] = createFrontendScriptCommand(options.packageManager, options.frontendDir, "dev")
     base.scripts["build:web"] = createFrontendScriptCommand(options.packageManager, options.frontendDir, "build")
     base.scripts["lint:web"] = createFrontendScriptCommand(options.packageManager, options.frontendDir, "lint")
@@ -466,10 +501,37 @@ ${options.frontendDir === "." ? `- \`${run} dev:web\`: run the Vite frontend onl
 
 - \`reset.config.json\`: desktop app metadata and runtime configuration
 - \`${webPath}\`: web frontend source
+- \`backend/\`: optional TypeScript sidecar backend
 - \`.reset/\`: generated build output and native runtime cache
 `
 }
 
+function createBackendPackageJson(options) {
+  return {
+    name: `${options.appName}-backend`,
+    private: true,
+    version: "0.1.0",
+    type: "module",
+    dependencies: {
+      "@reset-framework/backend": options.backendDependencySpec
+    }
+  }
+}
+
+async function writeBackendFiles(options) {
+  const backendDir = path.join(options.targetDir, "backend")
+  const backendSrcDir = path.join(backendDir, "src")
+
+  await mkdir(backendSrcDir, { recursive: true })
+  await writeFile(
+    path.join(backendDir, "package.json"),
+    JSON.stringify(createBackendPackageJson(options), null, 2) + "\n",
+    "utf8"
+  )
+  await writeFile(path.join(backendDir, "tsconfig.json"), backendTsconfig, "utf8")
+  await writeFile(path.join(backendSrcDir, "index.ts"), backendStarterSource, "utf8")
+}
+
 async function writeRootPackageFiles(options) {
   await writeFile(
     path.join(options.targetDir, "README.md"),
@@ -501,6 +563,16 @@ async function writeProjectFiles(options) {
           frontendDir: options.frontendDir,
           styling: options.styling
         },
+        security: {
+          permissions: Array.from(
+            new Set([
+              ...(Array.isArray(templateConfig.security?.permissions)
+                ? templateConfig.security.permissions
+                : []),
+              "backend.*"
+            ])
+          )
+        },
         window: {
           ...templateConfig.window,
           title: options.productName
@@ -567,6 +639,7 @@ async function collectCreateAppOptions(context, templates) {
       templateDir: path.join(frameworkPaths.templatesDir, defaults.templateName),
       templateConfigPath: path.join(frameworkPaths.templatesDir, defaults.templateName, "reset.config.json"),
       sourceFrontendDir: path.join(frameworkPaths.templatesDir, defaults.templateName, "frontend"),
+      backendDependencySpec: resolveBackendDependencySpec(frameworkPaths),
       cliDependencySpec: resolveCliDependencySpec(frameworkPaths),
       sdkDependencySpec: resolveSdkDependencySpec(frameworkPaths),
       packageManager: resolvePackageManagerOption(context),
@@ -723,6 +796,7 @@ async function collectCreateAppOptions(context, templates) {
     templateDir: path.join(frameworkPaths.templatesDir, selected.templateName),
     templateConfigPath: path.join(frameworkPaths.templatesDir, selected.templateName, "reset.config.json"),
     sourceFrontendDir: path.join(frameworkPaths.templatesDir, selected.templateName, "frontend"),
+    backendDependencySpec: resolveBackendDependencySpec(frameworkPaths),
     cliDependencySpec: resolveCliDependencySpec(frameworkPaths),
     sdkDependencySpec: resolveSdkDependencySpec(frameworkPaths),
     packageManagerVersion: await resolvePackageManagerVersion(selected.packageManager),
@@ -777,6 +851,8 @@ export async function run(context) {
       ["plan", "Write config", path.join(options.targetDir, "reset.config.json")],
       ["plan", "Write ignore file", path.join(options.targetDir, ".gitignore")],
       ["plan", "Write app package", path.join(options.targetDir, "package.json")],
+      ["plan", "Write backend package", path.join(options.targetDir, "backend", "package.json")],
+      ["plan", "Write backend entry", path.join(options.targetDir, "backend", "src", "index.ts")],
       ["plan", "Write SDK bridge", path.join(targetFrontendDir, "src", "lib", "reset.ts")],
       ["plan", "Write Vite config", path.join(targetFrontendDir, "vite.config.ts")],
       ["plan", "Write TS config", path.join(targetFrontendDir, "tsconfig.app.json")]
@@ -797,7 +873,7 @@ export async function run(context) {
   }
 
   console.log("")
-  const progress = createProgress(options.installDependencies ? 6 : 5, "Scaffold")
+  const progress = createProgress(options.installDependencies ? 7 : 6, "Scaffold")
 
   await mkdir(options.targetDir, { recursive: true })
   progress.tick("Prepared project directory")
@@ -812,6 +888,9 @@ export async function run(context) {
   await applyFrontendOverrides(targetFrontendDir, options)
   progress.tick("Applied frontend package wiring")
 
+  await writeBackendFiles(options)
+  progress.tick("Wrote backend starter")
+
   const packageJsonPath = path.join(targetFrontendDir, "package.json")
   const frontendPackage = JSON.parse(await readFile(packageJsonPath, "utf8"))
 
@@ -821,6 +900,7 @@ export async function run(context) {
     frontendPackage.private = true
     frontendPackage.version = "0.1.0"
     frontendPackage.description = `${options.productName} desktop app`
+    frontendPackage.workspaces = ["backend"]
     frontendPackage.devDependencies = {
       ...frontendPackage.devDependencies,
       "reset-framework-cli": options.cliDependencySpec

package/src/lib/backend.js

@@ -0,0 +1,123 @@
+import path from "node:path"
+import { chmod, copyFile, mkdir, realpath } from "node:fs/promises"
+import { existsSync } from "node:fs"
+
+import { build as buildWithEsbuild } from "esbuild"
+
+import { logger } from "./logger.js"
+import { resolveOptionalBackendEntry } from "./project.js"
+
+function isRuntimeExecutableName(name) {
+  const normalized = name.toLowerCase()
+  return normalized === "node" || normalized === "node.exe" || normalized === "bun" || normalized === "bun.exe"
+}
+
+function uniqueNonEmpty(items) {
+  return [...new Set(items.filter(Boolean))]
+}
+
+function resolvePathExecutable(commandName) {
+  const pathValue = process.env.PATH ?? ""
+  const searchDirectories = pathValue.split(path.delimiter).filter(Boolean)
+  const extensions =
+    process.platform === "win32"
+      ? uniqueNonEmpty(["", ...(process.env.PATHEXT?.split(";") ?? [".EXE", ".CMD", ".BAT", ".COM"])])
+      : [""]
+
+  for (const directory of searchDirectories) {
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${commandName}${extension}`)
+      if (existsSync(candidate)) {
+        return candidate
+      }
+    }
+  }
+
+  return null
+}
+
+function resolveSidecarRuntimeBinary() {
+  const candidates = uniqueNonEmpty([
+    process.execPath,
+    resolvePathExecutable("node"),
+    resolvePathExecutable("bun")
+  ])
+
+  for (const candidate of candidates) {
+    if (!candidate || !existsSync(candidate)) {
+      continue
+    }
+
+    if (isRuntimeExecutableName(path.basename(candidate))) {
+      return candidate
+    }
+  }
+
+  return null
+}
+
+function resolveBackendBuildDir(appPaths, mode) {
+  return path.join(appPaths.appRoot, ".reset", "backend", mode)
+}
+
+export async function prepareAppBackend(frameworkPaths, appPaths, mode) {
+  const entryPath = resolveOptionalBackendEntry(appPaths)
+  if (!entryPath) {
+    return null
+  }
+
+  const runtimeExecutablePath = resolveSidecarRuntimeBinary()
+  if (!runtimeExecutablePath) {
+    throw new Error(
+      "Could not resolve a JavaScript runtime for the Reset backend sidecar. Install Node.js or Bun."
+    )
+  }
+
+  const outputDir = resolveBackendBuildDir(appPaths, mode)
+  const bundleEntryPath = path.join(outputDir, "app.mjs")
+  const runnerPath = path.join(frameworkPaths.backendPackage.packageRoot, "src", "runner.js")
+  const supportModulePath = path.join(frameworkPaths.backendPackage.packageRoot, "src", "index.js")
+
+  await mkdir(outputDir, { recursive: true })
+  await buildWithEsbuild({
+    absWorkingDir: appPaths.appRoot,
+    entryPoints: [entryPath],
+    outfile: bundleEntryPath,
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    target: "node20",
+    sourcemap: mode === "dev" ? "inline" : false,
+    logLevel: "silent"
+  })
+
+  return {
+    entryPath,
+    bundleEntryPath,
+    runnerPath,
+    supportModulePath,
+    runtimeExecutablePath,
+    runtimeName: path.basename(runtimeExecutablePath),
+    workingDirectory: appPaths.appRoot
+  }
+}
+
+export async function stageAppBackend(backendArtifact, outputPaths) {
+  if (!backendArtifact) {
+    return
+  }
+
+  logger.info(`Staging backend sidecar into ${outputPaths.bundledBackendDir}`)
+
+  const resolvedRuntimePath = await realpath(backendArtifact.runtimeExecutablePath)
+
+  await mkdir(outputPaths.bundledBackendDir, { recursive: true })
+  await copyFile(backendArtifact.bundleEntryPath, outputPaths.bundledBackendEntryPath)
+  await copyFile(backendArtifact.runnerPath, outputPaths.bundledBackendRunnerPath)
+  await copyFile(backendArtifact.supportModulePath, outputPaths.bundledBackendSupportModulePath)
+  await copyFile(resolvedRuntimePath, outputPaths.bundledBackendRuntimePath)
+
+  if (process.platform !== "win32") {
+    await chmod(outputPaths.bundledBackendRuntimePath, 0o755)
+  }
+}

package/src/lib/output.js

@@ -2,6 +2,7 @@ import path from "node:path"
 import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises"
 import { existsSync } from "node:fs"
 
+import { stageAppBackend } from "./backend.js"
 import { logger } from "./logger.js"
 import { runCommand } from "./process.js"
 import {
@@ -118,7 +119,7 @@ function escapePowerShellLiteral(value) {
 }
 
 export async function stageMacOSAppBundle(frameworkPaths, frameworkBuildPaths, config, options = {}) {
-  const { dryRun = false, outputPaths, configPath, preferSource = false } = options
+  const { dryRun = false, outputPaths, configPath, preferSource = false, backendArtifact = null } = options
   const runtimeSourceBundle = resolveFrameworkRuntimeOutputDir(frameworkPaths, frameworkBuildPaths, "release", {
     mustExist: !dryRun,
     preferSource
@@ -140,6 +141,12 @@ export async function stageMacOSAppBundle(frameworkPaths, frameworkBuildPaths, c
     logger.info(`- copy ${runtimeSourceBundle} -> ${outputPaths.appBundlePath}`)
     logger.info(`- copy ${configPath} -> ${outputPaths.bundledConfigPath}`)
     logger.info(`- copy ${outputPaths.frontendDistDir} -> ${outputPaths.bundledFrontendDir}`)
+    if (backendArtifact) {
+      logger.info(`- copy ${backendArtifact.bundleEntryPath} -> ${outputPaths.bundledBackendEntryPath}`)
+      logger.info(`- copy ${backendArtifact.runnerPath} -> ${outputPaths.bundledBackendRunnerPath}`)
+      logger.info(`- copy ${backendArtifact.supportModulePath} -> ${outputPaths.bundledBackendSupportModulePath}`)
+      logger.info(`- copy ${backendArtifact.runtimeExecutablePath} -> ${outputPaths.bundledBackendRuntimePath}`)
+    }
     return outputPaths
   }
 
@@ -151,6 +158,7 @@ export async function stageMacOSAppBundle(frameworkPaths, frameworkBuildPaths, c
   await cp(configPath, outputPaths.bundledConfigPath, { force: true })
   await rm(outputPaths.bundledFrontendDir, { recursive: true, force: true })
   await cp(outputPaths.frontendDistDir, outputPaths.bundledFrontendDir, { recursive: true })
+  await stageAppBackend(backendArtifact, outputPaths)
   await writeFile(
     path.join(outputPaths.appBundlePath, "Contents", "Info.plist"),
     buildMacOSInfoPlist(config),
@@ -161,7 +169,7 @@ export async function stageMacOSAppBundle(frameworkPaths, frameworkBuildPaths, c
 }
 
 export async function stageWindowsAppBundle(frameworkPaths, frameworkBuildPaths, config, options = {}) {
-  const { dryRun = false, outputPaths, configPath, preferSource = false } = options
+  const { dryRun = false, outputPaths, configPath, preferSource = false, backendArtifact = null } = options
   const runtimeSourceBinary = resolveFrameworkRuntimeBinary(frameworkPaths, frameworkBuildPaths, "release", {
     mustExist: !dryRun,
     preferSource
@@ -188,6 +196,12 @@ export async function stageWindowsAppBundle(frameworkPaths, frameworkBuildPaths,
     logger.info(`- rename ${runtimeSourceBinary} -> ${outputPaths.appExecutablePath}`)
     logger.info(`- copy ${configPath} -> ${outputPaths.bundledConfigPath}`)
     logger.info(`- copy ${outputPaths.frontendDistDir} -> ${outputPaths.bundledFrontendDir}`)
+    if (backendArtifact) {
+      logger.info(`- copy ${backendArtifact.bundleEntryPath} -> ${outputPaths.bundledBackendEntryPath}`)
+      logger.info(`- copy ${backendArtifact.runnerPath} -> ${outputPaths.bundledBackendRunnerPath}`)
+      logger.info(`- copy ${backendArtifact.supportModulePath} -> ${outputPaths.bundledBackendSupportModulePath}`)
+      logger.info(`- copy ${backendArtifact.runtimeExecutablePath} -> ${outputPaths.bundledBackendRuntimePath}`)
+    }
     return outputPaths
   }
 
@@ -215,6 +229,7 @@ export async function stageWindowsAppBundle(frameworkPaths, frameworkBuildPaths,
   await cp(configPath, outputPaths.bundledConfigPath, { force: true })
   await rm(outputPaths.bundledFrontendDir, { recursive: true, force: true })
   await cp(outputPaths.frontendDistDir, outputPaths.bundledFrontendDir, { recursive: true })
+  await stageAppBackend(backendArtifact, outputPaths)
 
   return outputPaths
 }

package/src/lib/project.js

@@ -326,6 +326,11 @@ export function resolveFrameworkPaths() {
     path.join(packagesDir, "sdk"),
     resolvePackageInfo("@reset-framework/sdk", path.join(packagesDir, "sdk"))
   )
+  const backendPackage = resolveWorkspacePackageInfo(
+    "@reset-framework/backend",
+    path.join(packagesDir, "backend"),
+    resolvePackageInfo("@reset-framework/backend", path.join(packagesDir, "backend"))
+  )
   const schemaPackage = resolveWorkspacePackageInfo(
     "@reset-framework/schema",
     path.join(packagesDir, "schema"),
@@ -334,7 +339,7 @@ export function resolveFrameworkPaths() {
   const runtimePackage = resolveRuntimePackage(packagesDir)
   const isWorkspaceLayout =
     isWorkspacePackagesDir &&
-    [cliDir, sdkPackage.packageRoot, schemaPackage.packageRoot].every((packageRoot) =>
+    [cliDir, backendPackage.packageRoot, sdkPackage.packageRoot, schemaPackage.packageRoot].every((packageRoot) =>
       isPathInside(packagesDir, packageRoot)
     )
 
@@ -351,6 +356,7 @@ export function resolveFrameworkPaths() {
     frameworkRoot: nativePackage?.packageRoot ?? null,
     frameworkPackage: nativePackage,
     isWorkspaceLayout,
+    backendPackage,
     sdkPackage,
     schemaPackage,
     runtimePackage,
@@ -551,12 +557,24 @@ export function resolveAppPaths(appRoot) {
   return {
     appRoot,
     appPackageJsonPath: path.join(appRoot, "package.json"),
+    backendDir: path.join(appRoot, "backend"),
     frontendDir: path.join(appRoot, "frontend"),
     resetConfigPath: path.join(appRoot, "reset.config.json"),
     legacyResetConfigPath: path.join(appRoot, "frontend", "reset.config.json")
   }
 }
 
+export function resolveOptionalBackendEntry(appPaths) {
+  const candidates = [
+    path.join(appPaths.backendDir, "src", "index.ts"),
+    path.join(appPaths.backendDir, "src", "index.js"),
+    path.join(appPaths.backendDir, "index.ts"),
+    path.join(appPaths.backendDir, "index.js")
+  ]
+
+  return resolveExistingCandidate(candidates)
+}
+
 export function resolveConfigPath(appPaths) {
   if (existsSync(appPaths.resetConfigPath)) {
     return appPaths.resetConfigPath
@@ -571,6 +589,7 @@ export function resolveConfigPath(appPaths) {
 
 export function getFrameworkChecks(frameworkPaths) {
   return [
+    ["backend", frameworkPaths.backendPackage.packageJsonPath],
     ["sdk", frameworkPaths.sdkPackage.packageJsonPath],
     ["schema", frameworkPaths.schemaPackage.packageJsonPath],
     ["templates", frameworkPaths.templatesDir]
@@ -638,6 +657,7 @@ export function assertFrameworkInstall(frameworkPaths) {
 export function assertFrameworkSourceInstall(frameworkPaths) {
   const missing = [
     ["native source", frameworkPaths.frameworkPackage?.packageJsonPath],
+    ["backend", frameworkPaths.backendPackage.packageJsonPath],
     ["sdk", frameworkPaths.sdkPackage.packageJsonPath],
     ["cmake", frameworkPaths.rootCMakePath],
     ["runtime", frameworkPaths.runtimeDir],
@@ -784,6 +804,15 @@ export function resolveAppOutputPaths(appPaths, config) {
       : undefined,
     resourcesDir,
     bundledConfigPath: path.join(resourcesDir, "reset.config.json"),
+    bundledBackendDir: path.join(resourcesDir, "backend"),
+    bundledBackendEntryPath: path.join(resourcesDir, "backend", "app.mjs"),
+    bundledBackendRunnerPath: path.join(resourcesDir, "backend", "runner.mjs"),
+    bundledBackendSupportModulePath: path.join(resourcesDir, "backend", "index.js"),
+    bundledBackendRuntimePath: path.join(
+      resourcesDir,
+      "backend",
+      process.platform === "win32" ? "backend-runtime.exe" : "backend-runtime"
+    ),
     bundledFrontendDir: path.join(resourcesDir, config.frontend.distDir),
     frontendDistDir: path.resolve(frontendDir, config.frontend.distDir),
     frontendEntryFile: path.resolve(
@@ -830,6 +859,14 @@ export function resolveSdkDependencySpec(frameworkPaths) {
   return `^${frameworkPaths.sdkPackage.version}`
 }
 
+export function resolveBackendDependencySpec(frameworkPaths) {
+  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.backendPackage.localFallback) {
+    return `file:${frameworkPaths.backendPackage.packageRoot}`
+  }
+
+  return `^${frameworkPaths.backendPackage.version}`
+}
+
 export function resolveCliDependencySpec(frameworkPaths) {
   if (frameworkPaths.isWorkspaceLayout || frameworkPaths.cliPackage.localFallback) {
     return `file:${frameworkPaths.cliPackage.packageRoot}`