Merge pull request #1 from getlarge/feat-add-windows-support

getlarge · web-flow · commit 05758cd5a81b · 2025-03-10T17:41:18.000+01:00
feat: add windows support
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -18,15 +18,11 @@ jobs:
         with:
           fetch-depth: 0
 
-      # This enables task distribution via Nx Cloud
-      # Run this command as early as possible, before dependencies are installed
-      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
-      # Uncomment this line to enable task distribution
       # - run: npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'npm'
 
       - run: npm ci --legacy-peer-deps
@@ -39,7 +35,8 @@ jobs:
     needs: main
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [20, 22]
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -49,7 +46,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: ${{ matrix.node }}
           cache: 'npm'
 
       - run: npm ci --legacy-peer-deps
diff --git a/README.md b/README.md
@@ -1,76 +1,116 @@
-# NxNodeSea
+# @getlarge/nx-node-sea
 
-<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
+A plugin for [Nx](https://nx.dev) that provides integration with [Node.js Single Executable Applications (SEA)](https://nodejs.org/api/single-executable-applications.html).
 
-✨ Your new, shiny [Nx workspace](https://nx.dev) is almost ready ✨.
+## Overview
 
-Run `npx nx graph` to visually explore what got created. Now, let's get you up to speed!
+This plugin helps you create Node.js Single Executable Applications (SEA) within your Nx workspace. It automates the process of generating SEA preparation blobs and creating standalone executables that bundle your Node.js application.
 
-## Finish your CI setup
+## Requirements
 
-[Click here to finish setting up your workspace!](https://cloud.nx.app/connect/oTjir14WOJ)
+- Node.js 20 or higher (SEA feature requirement)
+- Nx 20.0.6 or higher
 
-## Run tasks
+## Installation
 
-To run tasks with Nx use:
-
-```sh
-npx nx <target> <project-name>
+```bash
+npm install --save-dev @getlarge/nx-node-sea
 ```
 
-For example:
+## Usage
 
-```sh
-npx nx build myproject
-```
+### 1. Create a sea-config.json file
 
-These targets are either [inferred automatically](https://nx.dev/concepts/inferred-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) or defined in the `project.json` or `package.json` files.
+Create a `sea-config.json` file in your project's root directory:
 
-[More about running tasks in the docs &raquo;](https://nx.dev/features/run-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+```json
+{
+  "main": "dist/your-app/main.js",
+  "output": "dist/your-app/main.blob",
+  "disableExperimentalSEAWarning": false,
+  "useSnapshot": false,
+  "useCodeCache": false
+}
+```
 
-## Add new projects
+### 2. Configure the plugin in nx.json
+
+Add the plugin configuration to your `nx.json` file:
+
+```json
+{
+  "plugins": [
+    {
+      "plugin": "@getlarge/nx-node-sea",
+      "options": {
+        "seaTargetName": "sea-build",
+        "buildTarget": "build"
+      }
+    }
+  ]
+}
+```
 
-While you could add new projects to your workspace manually, you might want to leverage [Nx plugins](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) and their [code generation](https://nx.dev/features/generate-code?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) feature.
+> **Note:** The `buildTarget` option specifies the target that will be used to build your application before creating the SEA. The default value is `"build"`.
 
-To install a new plugin you can use the `nx add` command. Here's an example of adding the React plugin:
+### 3. Build your SEA
 
-```sh
-npx nx add @nx/react
+```bash
+nx run your-app:sea-build
 ```
 
-Use the plugin's generator to create new projects. For example, to create a new React app or library:
+This will:
 
-```sh
-# Genenerate an app
-npx nx g @nx/react:app demo
+1. Build your application using the specified build target
+2. Generate a SEA preparation blob
+3. Create a standalone executable
 
-# Generate a library
-npx nx g @nx/react:lib some-lib
-```
+## Configuration Options
 
-You can use `npx nx list` to get a list of installed plugins. Then, run `npx nx list <plugin-name>` to learn about more specific capabilities of a particular plugin. Alternatively, [install Nx Console](https://nx.dev/getting-started/editor-setup?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) to browse plugins and generators in your IDE.
+### Plugin Options
 
-[Learn more about Nx plugins &raquo;](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) | [Browse the plugin registry &raquo;](https://nx.dev/plugin-registry?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+| Option          | Description                                                  | Default       |
+| --------------- | ------------------------------------------------------------ | ------------- |
+| `buildTarget`   | The target to build your application before creating the SEA | `"build"`     |
+| `seaTargetName` | The name of the target that will be created to build the SEA | `"sea-build"` |
 
-[Learn more about Nx on CI](https://nx.dev/ci/intro/ci-with-nx#ready-get-started-with-your-provider?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+### SEA Config Options
 
-## Install Nx Console
+| Option                          | Description                                          | Required |
+| ------------------------------- | ---------------------------------------------------- | -------- |
+| `main`                          | Path to the main JavaScript file of your application | Yes      |
+| `output`                        | Path where the SEA blob will be generated            | Yes      |
+| `disableExperimentalSEAWarning` | Disable warnings about experimental feature          | No       |
+| `useSnapshot`                   | Use V8 snapshot for faster startup                   | No       |
+| `useCodeCache`                  | Use code cache for faster startup                    | No       |
+| `assets`                        | Record of assets to include in the blob              | No       |
 
-Nx Console is an editor extension that enriches your developer experience. It lets you run tasks, generate code, and improves code autocompletion in your IDE. It is available for VSCode and IntelliJ.
+## Platform Support
 
-[Install Nx Console &raquo;](https://nx.dev/getting-started/editor-setup?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+The plugin automatically handles platform-specific differences for:
 
-## Useful links
+- Linux
+- macOS (includes code signing)
+- Windows
 
-Learn more:
+## Learn More
+
+- [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html)
+- [Nx Build System](https://nx.dev/features/build)
+- [Postject](https://github.com/nodejs/postject) - Used for injecting the blob into the executable
+
+## Example Project Structure
+
+```
+my-app/
+├── sea-config.json
+├── project.json
+└── src/
+    └── main.ts
+```
 
-- [Learn about Nx on CI](https://nx.dev/ci/intro/ci-with-nx?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-- [Releasing Packages with Nx release](https://nx.dev/features/manage-releases?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-- [What are Nx plugins?](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+The plugin will create a standalone executable in the directory specified in `sea-config.json` (`output`).
 
-And join the Nx community:
+On macOS and Linux, the binary will be named `node`. On Windows, it will be named `node.exe`.
 
-- [Discord](https://go.nx.dev/community)
-- [Follow us on X](https://twitter.com/nxdevtools) or [LinkedIn](https://www.linkedin.com/company/nrwl)
-- [Our Youtube channel](https://www.youtube.com/@nxdevtools)
-- [Our blog](https://nx.dev/blog?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+You can find a complete working example in the e2e tests.
diff --git a/nx-node-sea-e2e/src/nx-node-sea.spec.ts b/nx-node-sea-e2e/src/nx-node-sea.spec.ts
@@ -1,11 +1,12 @@
 import { execSync, spawn } from 'node:child_process';
 import { once } from 'node:events';
-import { mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { inspect } from 'node:util';
 import { NxJsonConfiguration, readJsonFile, writeJsonFile } from '@nx/devkit';
 
 import type { NodeSeaPluginOptions, NodeSeaOptions } from 'nx-node-sea';
+import { platform } from 'node:process';
 
 describe('nx-node-sea', () => {
   let projectDirectory: string;
@@ -16,14 +17,14 @@ describe('nx-node-sea', () => {
 
     // The plugin has been built and published to a local registry in the jest globalSetup
     // Install the plugin built with the latest source code into the test repo
-    execSync(`npm install nx-node-sea@e2e`, {
+    execSync(`npm install @getlarge/nx-node-sea@e2e`, {
       cwd: projectDirectory,
       stdio: 'inherit',
       env: process.env,
     });
     updateNxJson(projectDirectory);
     seaConfig = createSeaConfig(projectDirectory);
-  }, 10_000);
+  }, 15_000);
 
   afterAll(() => {
     // Cleanup the test project
@@ -35,17 +36,18 @@ describe('nx-node-sea', () => {
 
   it('should be installed', () => {
     // npm ls will fail if the package is not installed properly
-    execSync('npm ls nx-node-sea', {
+    execSync('npm ls @getlarge/nx-node-sea', {
       cwd: projectDirectory,
       stdio: 'inherit',
     });
   });
 
   it('should build the SEA', async () => {
-    const cp = spawn('nx', ['run', 'sea-build'], {
+    const cp = spawn('nx', ['run', 'sea-build', '--verbose'], {
       cwd: projectDirectory,
       stdio: 'inherit',
-      timeout: 10_000,
+      timeout: 35_000,
+      shell: true,
     });
     cp.stdout?.on('data', (data) => {
       console.log(data.trim().toString());
@@ -59,8 +61,8 @@ describe('nx-node-sea', () => {
     const outputDirectory = join(projectDirectory, dirname(seaConfig.output));
     const files = readdirSync(outputDirectory);
     expect(files).toContain(basename(seaConfig.output));
-    expect(files).toContain('node');
-  }, 15_000);
+    expect(files).toContain(platform === 'win32' ? 'node.exe' : 'node');
+  }, 45_000);
 
   it.todo('should run the SEA');
 });
@@ -95,6 +97,17 @@ function createTestProject() {
   console.log(
     inspect(readJsonFile(join(projectDirectory, 'project.json')), { depth: 3 })
   );
+
+  // mock the build output
+  const buildOutputDirectory = join(projectDirectory, 'dist', projectName);
+  mkdirSync(buildOutputDirectory, { recursive: true });
+  writeFileSync(
+    join(buildOutputDirectory, 'main.js'),
+    'console.log("Hello World");'
+  );
+
+  console.log(`Created dummy build output in "${buildOutputDirectory}"`);
+
   return projectDirectory;
 }
 
@@ -104,7 +117,7 @@ function updateNxJson(projectDirectory: string): void {
   );
   nxJson.plugins ??= [];
   nxJson.plugins.push({
-    plugin: 'nx-node-sea',
+    plugin: '@getlarge/nx-node-sea',
     options: {
       seaTargetName: 'sea-build',
       buildTarget: 'build',
diff --git a/nx-node-sea/src/plugin.ts b/nx-node-sea/src/plugin.ts
@@ -9,7 +9,7 @@ import {
 } from '@nx/devkit';
 import { calculateHashForCreateNodes } from '@nx/devkit/src/utils/calculate-hash-for-create-nodes';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, posix, win32 } from 'node:path';
 import { platform, versions } from 'node:process';
 import { combineGlobPatterns } from 'nx/src/utils/globs';
 import { workspaceDataDirectory } from 'nx/src/utils/cache-directory';
@@ -144,32 +144,76 @@ function getSeaTargetConfiguration(
   const blobPath = nodeSeaOptions.output;
   const nodeBinPath = join(dirname(blobPath), 'node');
   // TODO: add nodeSeaOptions.assets to inputs??
+
   return {
     cache: true,
-    inputs: ['node', '{projectRoot}/sea-config.json', 'production'],
+    inputs: [
+      'node',
+      '{projectRoot}/sea-config.json',
+      'production',
+      {
+        externalDependencies: ['postject'],
+      },
+      {
+        runtime: 'node --version',
+      },
+      {
+        runtime: 'node --print "process.arch"',
+      },
+    ],
     // TODO: check if blobPath is relative, if yes append workspaceRoot
     outputs: [`{workspaceRoot}/${blobPath}`, `{workspaceRoot}/${nodeBinPath}`],
     dependsOn: [options.buildTarget],
     executor: 'nx:run-commands',
     options: {
       /**
        * @see https://nodejs.org/api/single-executable-applications.html
-       * @todo update commands for win support
        */
-      commands: [
-        'node --experimental-sea-config {projectRoot}/sea-config.json',
-        `cp $(command -v node) ${nodeBinPath}`,
-        platform === 'darwin' && `codesign --remove-signature ${nodeBinPath}`,
-        platform === 'darwin'
-          ? `npx postject ${nodeBinPath} NODE_SEA_BLOB ${blobPath} --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 --macho-segment-name NODE_SEA`
-          : `npx postject ${nodeBinPath} NODE_SEA_BLOB ${blobPath} --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`,
-        platform === 'darwin' && `codesign --sign - ${nodeBinPath}`,
-      ],
+      commands: getSeaCommands({ nodeBinPath, blobPath }),
       parallel: false,
     },
   };
 }
 
+function getSeaCommands(options: {
+  nodeBinPath: string;
+  blobPath: string;
+  sign?: boolean;
+}): string[] {
+  const { nodeBinPath, blobPath, sign = false } = options;
+  if (platform === 'darwin') {
+    return [
+      'node --experimental-sea-config {projectRoot}/sea-config.json',
+      `cp $(command -v node) ${nodeBinPath}`,
+      `codesign --remove-signature ${nodeBinPath}`,
+      `npx postject ${nodeBinPath} NODE_SEA_BLOB ${blobPath} --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 --macho-segment-name NODE_SEA`,
+      `codesign --sign - ${nodeBinPath}`,
+    ];
+  } else if (platform === 'linux') {
+    return [
+      'node --experimental-sea-config {projectRoot}/sea-config.json',
+      `cp $(command -v node) ${nodeBinPath}`,
+      `npx postject ${nodeBinPath} NODE_SEA_BLOB ${blobPath} --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`,
+    ];
+  } else if (platform === 'win32') {
+    const _nodeBinPath = join(
+      dirname(nodeBinPath.replaceAll(posix.sep, win32.sep)),
+      'node.exe'
+    );
+    const _blobPath = blobPath.replaceAll(posix.sep, win32.sep);
+    return [
+      'node --experimental-sea-config {projectRoot}/sea-config.json',
+      `node -e "require('fs').copyFileSync(process.execPath, 'main.exe')"`,
+      ...(sign ? [`signtool remove /s 'main.exe' `] : []),
+      `npx postject main.exe NODE_SEA_BLOB ${_blobPath} --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`,
+      ...(sign ? [`signtool sign /fd SHA256 main.exe`] : []),
+      `mv main.exe ${_nodeBinPath}`,
+    ];
+  } else {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+}
+
 function getNodeVersion() {
   return versions.node;
 }
diff --git a/tools/scripts/start-local-registry.ts b/tools/scripts/start-local-registry.ts
@@ -14,7 +14,7 @@ export default async () => {
   global.stopLocalRegistry = await startLocalRegistry({
     localRegistryTarget,
     storage,
-    verbose: false,
+    verbose: true,
   });
 
   await releaseVersion({
diff --git a/tsconfig.base.json b/tsconfig.base.json
