NodeJS Workspace Type

The NodeJS workspace type provides a runtime environment for JavaScript/TypeScript applications including Next.js, Nuxt, Express, and headless frontend projects.

Web Server Configuration

Unlike PHP workspaces where the web server invokes PHP-FPM directly, the NodeJS web server acts as a reverse proxy — it forwards incoming HTTP traffic to the port where your Node application is listening. Your application is responsible for handling requests and sending responses; the web server simply routes traffic to it.

Shell Environment

When you SSH into a NodeJS workspace, the following tools and paths are pre-configured:

Node.js & npm

# Check versions
node -v
npm -v

# Run a script
node app.js

# Install dependencies
npm install

# Run package scripts
npm run dev
npm run build
npm start

Yarn, pnpm, and Bun

Alternative package managers are supported. If your project uses one, the workspace will auto-detect it from your lock file and install it if needed:

yarn install
pnpm install
bun install

npx

Run packages without installing them globally:

npx create-next-app@latest
npx prisma migrate dev

Pre-Installed CLI Tools

Beyond Node.js and package managers, the following tools are available out of the box:

Tool	Command	Purpose
PM2	pm2	Process manager (see below)
Yarn	yarn	Package manager
AWS CLI	aws	AWS service management
Kiro CLI	kiro	AI-assisted development
MySQL client	mysql	Database access
PostgreSQL client	psql	Database access
MongoDB Shell	mongosh	MongoDB access
Git	git	Version control
jq	jq	JSON processing
rsync	rsync	File synchronization

Framework-Specific Usage

Next.js

cd /home/web/html

# Development server
npm run dev

# Production build
npm run build
npm start

# Lint
npm run lint

Tip

The workspace web server proxies requests to your Node process. Start your app on the port specified by the PORT environment variable (typically 3000) so the proxy can reach it.

Nuxt

cd /home/web/html

# Development
npm run dev

# Build and preview
npm run build
npm run preview

# Generate static site
npm run generate

Express / Custom Servers

cd /home/web/html

# Start server
node server.js

# Or with npm script
npm start

# Development with auto-reload (if configured)
npm run dev

Process Management with PM2

NodeJS workspaces use PM2 as the process manager. PM2 runs your application, restarts it on crash, and persists process state across workspace restarts.

How It Works

When the workspace environment starts, the following sequence runs automatically:

1. Check for a start command — If no start command is configured in the Ordin admin, the startup script exits and no app is launched. You can still SSH in and run things manually.

2. Check for the project directory — The app is expected to live in /home/web/project. If this directory doesn’t exist, startup is skipped.

3. Resurrect saved processes — If PM2 has a saved process list from a previous session (~/.pm2/dump.pm2), it restores those processes. If the saved start command matches the current configuration, the app is considered already running and no further action is taken.

4. Detect and install the package manager — If package.json exists, the workspace determines which package manager to use (see below) and installs it globally if it’s not already available.

5. Install dependencies — Runs <package-manager> install in the project directory.

6. Start the application — PM2 launches the app using the configured start command, registers it under the name app, and saves the process list for future restarts.

If you change the start command in the Ordin admin, PM2 detects the mismatch on next startup, removes the old process, and re-launches with the new command.

The start command and PM2 enablement are configured through the Ordin Workspace Manager admin — you don’t set these yourself.

Package Manager Detection

During startup, the workspace automatically detects which package manager to use for install, in this order of priority:

1. Explicit configuration — if set in the Ordin admin
2. Lock file detection — yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb/bun.lock → bun
3. Default — npm

If the detected package manager isn’t already installed, it will be installed globally via npm before running install.

Common PM2 Commands

# View running processes
pm2 list

# View application logs
pm2 logs
pm2 logs app

# Restart your application
pm2 restart app

# Stop your application
pm2 stop app

# Delete a process from PM2
pm2 delete app

# Monitor CPU/memory in real time
pm2 monit

# Save current process list (persists across restarts)
pm2 save

Tip

If you change your start command in the workspace configuration, PM2 detects the mismatch on next startup and automatically restarts the app with the new command.

Caution

If your Node process crashes repeatedly, PM2 will keep restarting it. Check pm2 logs to diagnose the issue. You can stop the restart loop with pm2 stop app.

Environment Variables

Ordin automatically injects environment variables into the workspace to pass configuration values to your application. These are set by the platform based on your workspace and project settings — you don’t manage them directly.

Commonly used variables:

Variable	Example	Description
WORKSPACE_DOMAIN_1	myapp.project.ordinlabs.io	Primary workspace URL
WORKSPACE_DB_HOST	db	Database hostname
WORKSPACE_DB_NAME	workspace_abc	Database name
WORKSPACE_DB_USER	root	Database user
WORKSPACE_DB_PASSWORD	(set automatically)	Database password
WORKSPACE_NAME	myapp	Workspace subdomain
PORT	3000	Port your app should listen on

Your application code can reference these to connect to services without hardcoding values. See Workspace Config Templates for the full list.

Common Tasks

Testing HTTP Output

curl -H "Host: $WORKSPACE_DOMAIN_1" http://localhost

Database Access

# MySQL
mysql -h db -u root -p $WORKSPACE_DB_NAME

# Or from your app via environment variables
DATABASE_URL="mysql://$WORKSPACE_DB_USER:$WORKSPACE_DB_PASSWORD@$WORKSPACE_DB_HOST/$WORKSPACE_DB_NAME"

Checking Logs

# PM2 application logs
pm2 logs

# Web server proxy logs
tail -f /var/log/nginx/error.log

File Structure

/home/web/
├── html/              # Web root (application code)
│   ├── package.json
│   ├── node_modules/
│   └── ...
├── .bashrc            # Personal shell config
└── .workspacerc       # Workspace-specific config

/shared/               # Shared across project workspaces
├── .profile           # Project-wide shell profile
├── .bashrc            # Project-wide bash config
├── bin/               # Shared scripts (in $PATH)
└── startup.d/         # Scripts run on environment start