GitNexus Universal Bundler CLI

1.0.2 verified Thu Apr 23 auth: no javascript

The `gitnexus-bundler` is a Command Line Interface (CLI) tool, currently at version `1.0.2`, specifically engineered to compile Node.js and Next.js applications into a single, self-contained CommonJS (`.cjs`) executable for deployment within GitNexus WebContainer environments. It streamlines the deployment process by bundling the entire backend server logic—leveraging `esbuild` for efficient compilation—and can optionally integrate and embed frontend static assets into the final `.cjs` artifact. This tool runs locally on the developer's machine, generating both the executable bundle and a `gitnexus.json` manifest for hosting. Its key differentiators include its targeted optimization for GitNexus deployments, support for full-stack applications with integrated frontend build steps and static asset embedding, and the production of a highly portable, single-file application executable, distinguishing it from multi-file serverless or container deployments. The package maintains an active development status, with updates focusing on features and stability.

Common errors

error Error: The module 'bcrypt' was compiled against a different Node.js version. This version of Node.js cannot load this module. ↓

cause Attempting to use a Node.js native C++ addon (like `bcrypt`, `sqlite3`, `sharp`) which is not compatible with the GitNexus WebContainer's runtime environment.

fix

Replace the problematic native module with a pure JavaScript alternative (e.g., bcryptjs for bcrypt) or refactor to use a cloud service that handles the native functionality externally.

error Error: listen EADDRNOTAVAIL: address not available 127.0.0.1:8080 ↓

cause Your application server is trying to bind to `127.0.0.1` (localhost) instead of `0.0.0.0`, or a port other than `8080`, which makes it inaccessible within the WebContainer.

fix

Update your server's listen call to app.listen(8080, '0.0.0.0', () => ...) to ensure it binds to the correct address and port for GitNexus.

error Refused to frame 'https://your-bundle-url.pages.dev/' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'". ↓

cause A security middleware (like Helmet) is setting restrictive Content Security Policy (CSP) headers that prevent the GitNexus WebContainer from embedding your application in an iframe.

fix

Configure your security middleware to disable or loosen specific CSP directives, particularly frame-ancestors, and potentially crossOrigin*Policy settings, as outlined in the Architectural Guidelines for GitNexus.

Warnings

breaking Applications bundled for GitNexus WebContainers must not use Node.js native C++ addons (e.g., `bcrypt`, `node-sass`, `canvas`, `sharp`, `sqlite3`, `puppeteer`). These modules are incompatible with the WebContainer environment due to their dependency on compiled C++ binaries. ↓

fix Replace native modules with pure JavaScript alternatives (e.g., `bcryptjs` for `bcrypt`, `sass` for `node-sass`), or leverage external cloud services for functionality requiring such libraries (e.g., Cloudinary for image processing instead of `sharp`).

gotcha Your Node.js application server must explicitly listen on port `8080` and host `0.0.0.0` to be accessible within the GitNexus WebContainer environment. ↓

fix Ensure your server initialization code uses `app.listen(8080, '0.0.0.0', ...)` or equivalent, rather than defaulting to `localhost` or other ports.

gotcha When using security middleware like Helmet, default Content Security Policy (CSP), Frameguard, and Cross-Origin policies can block your application within the GitNexus WebContainer, which operates in an iframe-based environment. ↓

fix Configure Helmet to relax or disable `contentSecurityPolicy`, `crossOriginEmbedderPolicy`, `crossOriginResourcePolicy`, `crossOriginOpenerPolicy`, and `frameguard` when deploying to GitNexus, as shown in the architectural guidelines.

gotcha While GitHub Releases can host your `.cjs` bundle for testing, it has significant limitations including 1 GB/month bandwidth on free accounts and requires manual uploads. It's not suitable for production or automated deployments. ↓

fix For production and reliable hosting, use a dedicated CDN or static file host like Cloudflare Pages, which offers unlimited bandwidth and a seamless deployment experience for static assets.

Install

npm install gitnexus-bundler

yarn add gitnexus-bundler

pnpm add gitnexus-bundler

Imports

gitnexus-bundler
wrong
```
gitnexus-bundler build -i src/server.js
```
correct
```
npx gitnexus-bundler build -i src/server.js
```
The `npx` invocation is the recommended way to use the CLI without a global installation. Direct invocation without `npx` only works if the package is globally installed or in your path.
build
wrong
```
npx gitnexus-bundler -i server.js
```
correct
```
npx gitnexus-bundler build -i server.js -f "npm run build" -s out
```
The `build` subcommand is mandatory to initiate the bundling process and is where all options are applied.
Global Installation
wrong
```
npx gitnexus-bundler build -i src/index.ts
```
correct
```
npm install -g gitnexus-bundler
gitnexus-bundler build -i src/index.ts
```
If you have globally installed `gitnexus-bundler`, you can run it directly by its name. Using `npx` is redundant in this case, though harmless.

Quickstart

Demonstrates bundling a simple Express.js backend into a GitNexus Cloud Executable (`.cjs`) using `npx`.

npm init -y
npm install express

// src/server.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello from GitNexus Bundler!');
});

app.listen(8080, '0.0.0.0', () => {
  console.log('Server listening on http://0.0.0.0:8080');
});

// Bundle the backend application
npx gitnexus-bundler build -i src/server.js -o gitnexus-bundle.cjs

console.log('\nBundle created: gitnexus-bundle.cjs');
console.log('Next, host gitnexus-bundle.cjs (e.g., on Cloudflare Pages) and update gitnexus.json');