Product documentation
Citrix Secure Developer Spaces™
View PDF

Quick start: Hello World for Node.js developers

July 10, 2026
Contributed by: 
C

Developer

This guide helps you get productive with Node.js, JavaScript, or TypeScript development in Citrix Secure Developer Spaces™ (SDS). It covers common workflows — running applications, debugging, testing, using Docker, and managing secrets.

You can read this guide standalone, or follow along hands-on using the Hello World workspace (a self-contained Next.js + PostgreSQL demo app). Collapsible “Try it” sections provide concrete exercises using the Hello World environment.

Before you begin

What your workspace includes

Your Project Owner or platform administrator has set up a Node.js workspace template with everything you need pre-installed. A typical Node.js template includes:

Component What it provides
Node.js runtime The specific Node.js version your project requires (for example, Node 20 LTS)
Package manager npm, yarn, or pnpm — whichever your team uses
Build tools TypeScript compiler, bundlers (Vite, webpack, esbuild), linters (ESLint)
VS Code extensions ESLint, Prettier, TypeScript language support, and other team-standard extensions
Docker Docker-in-Docker for running databases, services, or containers
Git and SSH Pre-configured access to your repositories

You don’t need to install any of this yourself — it’s already in the template. If something is missing, contact your Project Owner to update the workspace template.

Tip: To check which Node.js version and tools are available, open a terminal and run:

node --version
npm --version
<!--NeedCopy-->

Running your application

Start backing services first

If your application depends on a database or other services, start them before the dev server. In the Hello World workspace, PostgreSQL runs in a Docker container that you start with Docker Compose (see Using Docker for services).

Install dependencies

Navigate to your project and install packages:

cd /home/developer/my-project
npm install    # or: yarn install / pnpm install
<!--NeedCopy-->

Start the dev server 

npm run dev    # or: yarn dev / pnpm dev
<!--NeedCopy-->

When your dev server starts, VS Code automatically detects the open port and shows a notification: “A workspace application is available at the port [number]”. Select Preview to open your application in VS Code’s built-in Simple Browser.

VS Code port notification with Preview button

The application opens in a new editor tab alongside your code. The preview URL follows the pattern https://<workspace-id>-port-<number>.proxy.<domain>.

You can also:

  • Copy the preview URL and open it in any browser tab.
  • Use the Workspace Apps panel in the SDS console to see all exposed ports.

Important: If the notification doesn’t appear, make sure your application binds to 0.0.0.0 rather than localhost. Most frameworks do this by default in dev mode, but you may need to configure it:

npx vite --host 0.0.0.0        # Vite
npx next dev -H 0.0.0.0        # Next.js
<!--NeedCopy-->

Or in code (Express): app.listen(3000, '0.0.0.0')

Try it: Run the Hello World app

The Hello World app needs its PostgreSQL database running first. Start the database with Docker Compose, then start the dev server:

cd /home/developer/demo-nodejs-postgresql-main
docker-compose up -d    # start PostgreSQL (first run initializes the database)
yarn dev
<!--NeedCopy-->

Select Preview when the port notification appears. You should see the ACME Project user management interface. Open the Users page and try adding a user — this sends a request through the API to PostgreSQL and back.

If the Users page shows an error, the database probably isn’t running yet. Confirm the container is up with docker ps (you should see project-acme-db), then reload the page. See Using Docker for services for the full database exercise.

Debugging your application

Debugging in SDS works exactly the same as on your local machine — same tools, same workflows, same keyboard shortcuts. There’s nothing new to learn.

VS Code debugger

  1. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
  2. If your project has a .vscode/launch.json, select the configuration and press F5.
  3. If no launch configuration exists, VS Code can automatically detect Node.js processes. Select Node.js when prompted.

JavaScript Debug Terminal

  1. Open a new terminal and select JavaScript Debug Terminal from the dropdown.
  2. Run your application as usual (for example, npm run dev). The debugger attaches automatically.
  3. Set breakpoints in your code — they’ll be hit as requests come in.

Terminal-based debugging 

node --inspect your-script.js
node --inspect ./node_modules/.bin/next dev
<!--NeedCopy-->

Try it: Debug the Hello World API

  1. Make sure the database is running (docker-compose up -d — see Using Docker for services).
  2. Open src/app/api/users/route.ts.
  3. Select the gutter next to a line inside the GET function to set a breakpoint.
  4. Open a JavaScript Debug Terminal and run yarn dev.
  5. In the browser preview, navigate to the Users page (which fetches users from the database). The home page is static and does not trigger the API.
  6. The debugger pauses at your breakpoint. Inspect the result variable to see the database results (result.rows).

Try it: Debug a slow request (client-side network latency)

The Hello World app includes a built-in Slow mode toggle that adds a 2–3 second delay in the browser before each API call — useful for testing loading states and spinners. This delay lives in src/app/utils/delay.ts and runs client-side, so you debug it with your browser’s DevTools rather than the JavaScript Debug Terminal used for server-side code above.

  1. With yarn dev running, open the app preview in a browser tab (copy the preview URL — VS Code’s built-in Simple Browser doesn’t expose DevTools). Toggle Slow in the navigation bar (the hourglass/bolt switch). The setting is stored in the browser.
  2. Open your browser’s DevTools (F12) and select the Network tab. Reload the Users page: each /api/users request now takes 2–3 seconds. Toggle Fast and reload to compare — the delay is gone.
  3. To step through the delay itself, open the Sources tab, find src/app/utils/delay.ts (Next.js serves source maps in dev), and set a breakpoint inside simulateDelay. Reload the Users page — execution pauses there, and you can inspect isSlowMode and slowDelay to see the latency being applied.

This is the client-side counterpart to the API exercise above: debug server-side code with the JavaScript Debug Terminal, and browser-side code with your browser’s DevTools — handy for reproducing slow-network conditions and verifying spinners, skeletons, and timeout handling.

Using Docker for services

Many Node.js projects depend on services like databases, caches, or message queues. SDS supports Docker-in-Docker, so you can run these inside your workspace using Docker Compose — just like on a local machine.

Note: The Hello World workspace uses the docker-compose command (Compose v1 syntax). If your own template provides the Docker Compose plugin instead, use docker compose (with a space) — the subcommands are otherwise identical.

Common pattern 

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
    ports:
      - "5432:5432"
<!--NeedCopy-->

docker-compose up -d       # Start services in background
docker ps                  # Verify they're running
docker-compose down        # Stop services
<!--NeedCopy-->

Your application connects to these services through localhost — same as local development.

Try it: Start and explore the database in the Hello World workspace

The Hello World workspace ships with a docker-compose.yml that defines a PostgreSQL container. Start it and explore:

cd /home/developer/demo-nodejs-postgresql-main

# Start PostgreSQL (first run initializes the schema from init.sql)
docker-compose up -d

# View running containers — you should see project-acme-db
docker ps

# Check the PostgreSQL logs
docker logs project-acme-db

# Connect directly to the database
docker exec -it project-acme-db psql -U acme_user -d project_acme

# Query the users table
SELECT * FROM users;
\q
<!--NeedCopy-->

When you’re done, you can stop the database with docker-compose down (your data is preserved in a named volume) and start it again later with docker-compose up -d.

Using secrets and environment variables

Most Node.js applications rely on environment variables for API keys, database credentials, and service URLs. In SDS, you manage these through secrets — instead of manually maintaining .env files or exporting variables in each session.

How secrets work

Secrets configured in your SDS profile (or by your Project Owner at the project level) are automatically injected into your workspaces as environment variables. This means:

  • They persist across sessions. No need to re-export after a workspace restart.
  • They work across workspaces. The same API key is available in all your workspaces.
  • They’re secure. Stored encrypted, never in your code or Git history.

Accessing secrets in your code 

// Secrets appear as standard environment variables
const dbPassword = process.env.DB_PASSWORD;
const apiKey = process.env.MY_API_KEY;
<!--NeedCopy-->

When to use secrets vs. .env files

Use case Approach
API keys, tokens, credentials SDS secrets — persists across workspaces and restarts
Project-specific config (port, debug flags) .env file in your repo (committed or gitignored as appropriate)
Shared team secrets (database, services) Ask your Project Owner to configure project-level secrets

Tip: If your project uses a .env file for local development, you can still use it in SDS. But for sensitive values, prefer SDS secrets — they’re more secure and you don’t risk accidentally committing them.

Try it: Confirm the injected secrets in the Hello World workspace

The Hello World app connects to PostgreSQL using the secrets you added when you created the workspace (see Hello World workspace, Step 1). First, confirm they are available in your workspace by printing them in a terminal:

echo $DB_HOST       # localhost
echo $DB_PORT       # 5432
echo $DB_NAME       # project_acme
echo $DB_USER       # acme_user
echo $DB_PASSWORD   # acme_password
<!--NeedCopy-->

If each command prints the expected value, the secrets are configured correctly. If any are empty, you most likely skipped the secrets step when creating the workspace — revisit Hello World workspace, Step 1 and add them. (In a real project, these are typically configured once as project-level secrets by your Project Owner.)

Now look at src/lib/db.ts to see how the app reads these environment variables, falling back to local defaults only when they’re absent:

const pool = process.env.DATABASE_URL
  ? new Pool({ connectionString: process.env.DATABASE_URL })
  : new Pool({
      host: process.env.DB_HOST || 'localhost',
      port: parseInt(process.env.DB_PORT || '5432'),
      database: process.env.DB_NAME || 'project_acme',
      user: process.env.DB_USER || 'acme_user',
      password: process.env.DB_PASSWORD || 'acme_password',
    })
<!--NeedCopy-->

The five DB_* variables are the standard way to configure the connection (DB_PORT is optional and defaults to 5432). DATABASE_URL is an optional single-string alternative — if it is set, it takes precedence and the individual DB_* values are ignored.

Finally, try adding your own personal secret: go to Profile > Security > Personal secrets, add MY_API_KEY = test123, restart the workspace, and verify it’s available with echo $MY_API_KEY.

Working with TypeScript

If your project uses TypeScript, the compiler and language service should already be available in your template. TypeScript IntelliSense works automatically in VS Code.

# Check TypeScript version
npx tsc --version

# Run type checking
npx tsc --noEmit

# Install missing type definitions
npm install --save-dev @types/library-name
<!--NeedCopy-->

Try it: Type-check the Hello World project 

cd /home/developer/demo-nodejs-postgresql-main
yarn type-check
<!--NeedCopy-->

Try introducing a type error — for example, change a string parameter to a number in src/app/api/users/route.ts — and run yarn type-check again to see the error output.

Linting and formatting

ESLint and Prettier are typically pre-configured in your workspace template. They run automatically in VS Code (format on save, inline lint errors).

# Lint the codebase
npx eslint .

# Format all files
npx prettier --write .
<!--NeedCopy-->

Try it: Lint the Hello World project 

cd /home/developer/demo-nodejs-postgresql-main
yarn lint
<!--NeedCopy-->

Try adding an unused variable to any .ts file and re-run lint to see it flagged.

Running tests

Run your project’s test suite with the configured test runner:

npm test              # Default test script
npx jest --watch      # Jest in watch mode
npx vitest            # Vitest
npx mocha             # Mocha
<!--NeedCopy-->

Making a code change (hot reload)

Hot reload works as expected — tools like Vite, Next.js, and nodemon detect file changes and reload automatically. No difference from local development.

Try it: Edit a component in the Hello World app

  1. With yarn dev running, open src/app/page.tsx.
  2. Find the page heading and change it (for example, “Welcome to My ACME Project”).
  3. Save the file.
  4. The browser preview updates automatically within seconds — no restart needed.

Sharing your application with Workspace Apps

When your dev server is running, you can share it with teammates for testing or review — without deploying to a staging environment. SDS Workspace Apps let you expose a running application to other project members.

Create a Workspace App

  1. In the SDS console, navigate to the Project Overview page.
  2. From the Workspace Apps drop-down menu, select Create Workspace App.
  3. Configure the app:
    • Port: The port your application runs on (for example, 3000)
    • Name: A display name (for example, “Frontend Dev Server”)
    • Share: Choose who can access it — Public, Project Sharing (all project members), or specific members
  4. Select Save.

Alternatively, select the “…“ icon on your workspace and select Edit Ports to add or manage workspace apps.

Your application is now accessible to others through a shared URL. They can view it in their browser without needing their own workspace running.

When to use Workspace Apps

Scenario Benefit
Code review Reviewer sees your changes running live, not just a diff
Design feedback Designers access the UI without cloning or building
QA testing Testers interact with your feature branch before merge
Pair programming Colleague views your app while you debug together

Try it: Share the Hello World app with your team

  1. With yarn dev running in the Hello World workspace, go to the SDS console.
  2. On the Project Overview page, select Create Workspace App from the Workspace Apps drop-down menu.
  3. Set the name to “ACME Project” and the port to 3000.
  4. Under Share, choose Project Sharing so all project members can access it.
  5. Save. Copy the generated URL and send it to a teammate — they can open it in their browser and interact with the app.

Learn more about Workspace Apps

Persisting your dependencies

Node modules installed through npm install are stored under /home/developer/my-project/node_modules, which is inside your persistent home directory. Your dependencies persist between workspace sessions.

For global npm packages, install them in your home directory:

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
<!--NeedCopy-->

Add the PATH line to your .bashrc or .zshrc (through your SDS profile configuration) to make it permanent.

For anything that needs to be installed system-wide (outside /home/developer), use a startup script or ask your Project Owner to include it in the template image. You have root access and can install anywhere, but changes outside /home/developer are not persistent and will be lost on the next restart.

Learn more about persistent changes

Tips for Node.js development in SDS

  • Hot reload works as expected. Vite, Next.js, nodemon — all detect changes and reload automatically.
  • Use the same Git workflow. Branch, commit, push, create PRs — identical to local development.
  • Port detection is automatic. When you start a dev server, VS Code detects the port and prompts you to preview.
  • Multi-service projects work too. Run multiple services (frontend on 3000, API on 4000) — both are accessible through Workspace Apps.
  • Need a database? Use Docker Compose to run PostgreSQL, MongoDB, Redis, or any other service inside your workspace.
  • Disk space is adjustable. If you run low, increase your workspace disk through Edit Workspace > Resources > Disk size.

Troubleshooting

Issue Solution
node or npm not found You may have selected the wrong template. Contact your Project Owner.
Wrong Node.js version If nvm is available, run nvm use <version>. Otherwise, ask your Project Owner to update the template.
npm install succeeds but packages disappear after restart Packages installed outside /home/developer are not persistent. Ensure your project and node_modules are under /home/developer.
Dev server starts but app isn’t accessible Ensure the server binds to 0.0.0.0, not localhost. Check the Workspace Apps panel for the exposed port.
App loads but database calls fail Make sure the database container is running: docker ps. If not, start it with docker-compose up -d and reload the page.
Changes not detected by hot reload Try increasing the file watcher limit: echo fs.inotify.max_user_watches=524288 \| sudo tee -a /etc/sysctl.conf && sudo sysctl -p
ENOSPC: no space left on device Delete node_modules from unused projects, or increase your workspace disk space through Edit Workspace > Resources > Disk size.
Docker containers won’t start Verify Docker is running: docker info. If not, your workspace may not have privileged mode enabled — contact your Project Owner.

Next steps

  • Share your running app. Use Workspace Apps to give teammates a live preview without deploying. See Workspace Apps.
  • Customize your setup. Add VS Code extensions, shell aliases, or startup scripts to your profile configuration. See Set up your account, Step 3.
  • Learn about workspace persistence. Understand what’s saved between sessions. See What persists in an SDS Workspace.

Get help

  • Check your project’s README for project-specific setup instructions.
  • Ask your Project Owner about template contents, missing tools, or database access.
  • Browse the SDS docs for detailed guides.
Quick start: Hello World for Node.js developers
July 10, 2026
Contributed by: 
C
July 10, 2026
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.