Skip to content

Commit 30d670a

Browse files
getlargegetlarge
committed
docs: update README for @getlarge/nx-node-sea plugin with installation and usage instructions
1 parent b7898d5 commit 30d670a

File tree

1 file changed

+85
-45
lines changed

1 file changed

+85
-45
lines changed

‎README.md‎

Lines changed: 85 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,116 @@
1-
# NxNodeSea
1+
# @getlarge/nx-node-sea
22

3-
<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>
3+
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).
44

5-
✨ Your new, shiny [Nx workspace](https://nx.dev) is almost ready ✨.
5+
## Overview
66

7-
Run `npx nx graph` to visually explore what got created. Now, let's get you up to speed!
7+
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.
88

9-
## Finish your CI setup
9+
## Requirements
1010

11-
[Click here to finish setting up your workspace!](https://cloud.nx.app/connect/oTjir14WOJ)
11+
- Node.js 20 or higher (SEA feature requirement)
12+
- Nx 20.0.6 or higher
1213

13-
## Run tasks
14+
## Installation
1415

15-
To run tasks with Nx use:
16-
17-
```sh
18-
npx nx <target> <project-name>
16+
```bash
17+
npm install --save-dev @getlarge/nx-node-sea
1918
```
2019

21-
For example:
20+
## Usage
2221

23-
```sh
24-
npx nx build myproject
25-
```
22+
### 1. Create a sea-config.json file
2623

27-
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.
24+
Create a `sea-config.json` file in your project's root directory:
2825

29-
[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)
26+
```json
27+
{
28+
"main": "dist/your-app/main.js",
29+
"output": "dist/your-app/main.blob",
30+
"disableExperimentalSEAWarning": false,
31+
"useSnapshot": false,
32+
"useCodeCache": false
33+
}
34+
```
3035

31-
## Add new projects
36+
### 2. Configure the plugin in nx.json
37+
38+
Add the plugin configuration to your `nx.json` file:
39+
40+
```json
41+
{
42+
"plugins": [
43+
{
44+
"plugin": "@getlarge/nx-node-sea",
45+
"options": {
46+
"seaTargetName": "sea-build",
47+
"buildTarget": "build"
48+
}
49+
}
50+
]
51+
}
52+
```
3253

33-
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.
54+
> **Note:** The `buildTarget` option specifies the target that will be used to build your application before creating the SEA. The default value is `"build"`.
3455
35-
To install a new plugin you can use the `nx add` command. Here's an example of adding the React plugin:
56+
### 3. Build your SEA
3657

37-
```sh
38-
npx nx add @nx/react
58+
```bash
59+
nx run your-app:sea-build
3960
```
4061

41-
Use the plugin's generator to create new projects. For example, to create a new React app or library:
62+
This will:
4263

43-
```sh
44-
# Genenerate an app
45-
npx nx g @nx/react:app demo
64+
1. Build your application using the specified build target
65+
2. Generate a SEA preparation blob
66+
3. Create a standalone executable
4667

47-
# Generate a library
48-
npx nx g @nx/react:lib some-lib
49-
```
68+
## Configuration Options
5069

51-
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.
70+
### Plugin Options
5271

53-
[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)
72+
| Option | Description | Default |
73+
| --------------- | ------------------------------------------------------------ | ------------- |
74+
| `buildTarget` | The target to build your application before creating the SEA | `"build"` |
75+
| `seaTargetName` | The name of the target that will be created to build the SEA | `"sea-build"` |
5476

55-
[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)
77+
### SEA Config Options
5678

57-
## Install Nx Console
79+
| Option | Description | Required |
80+
| ------------------------------- | ---------------------------------------------------- | -------- |
81+
| `main` | Path to the main JavaScript file of your application | Yes |
82+
| `output` | Path where the SEA blob will be generated | Yes |
83+
| `disableExperimentalSEAWarning` | Disable warnings about experimental feature | No |
84+
| `useSnapshot` | Use V8 snapshot for faster startup | No |
85+
| `useCodeCache` | Use code cache for faster startup | No |
86+
| `assets` | Record of assets to include in the blob | No |
5887

59-
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.
88+
## Platform Support
6089

61-
[Install Nx Console &raquo;](https://nx.dev/getting-started/editor-setup?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
90+
The plugin automatically handles platform-specific differences for:
6291

63-
## Useful links
92+
- Linux
93+
- macOS (includes code signing)
94+
- Windows
6495

65-
Learn more:
96+
## Learn More
97+
98+
- [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html)
99+
- [Nx Build System](https://nx.dev/features/build)
100+
- [Postject](https://github.com/nodejs/postject) - Used for injecting the blob into the executable
101+
102+
## Example Project Structure
103+
104+
```
105+
my-app/
106+
├── sea-config.json
107+
├── project.json
108+
└── src/
109+
└── main.ts
110+
```
66111

67-
- [Learn about Nx on CI](https://nx.dev/ci/intro/ci-with-nx?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
68-
- [Releasing Packages with Nx release](https://nx.dev/features/manage-releases?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
69-
- [What are Nx plugins?](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
112+
The plugin will create a standalone executable in the directory specified in `sea-config.json` (`output`).
70113

71-
And join the Nx community:
114+
On macOS and Linux, the binary will be named `node`. On Windows, it will be named `node.exe`.
72115

73-
- [Discord](https://go.nx.dev/community)
74-
- [Follow us on X](https://twitter.com/nxdevtools) or [LinkedIn](https://www.linkedin.com/company/nrwl)
75-
- [Our Youtube channel](https://www.youtube.com/@nxdevtools)
76-
- [Our blog](https://nx.dev/blog?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
116+
You can find a complete working example in the e2e tests.

0 commit comments

Comments
 (0)