logo

Node.js

Namespace natively supports Javascript/TypeScript apps (on the server, in the browser or both). There are two native integrations to choose from:

  • To define a server or a hybrid (server/browser) app, use the nodejs integration.
  • To define a web application (static JS/CSS/HTML, with separate backends), use the web integration.

See the reference for more details about the syntax.

nodejs

The nodejs integration allows to avoid writing a custom Dockerfile and use a combination of the .cue file and the existing configuration (e.g. package.json) instead to build a Node.js image easier. Also file sync between the workstation code and the container is set up, enabling hot reload.

Existing configuration: package manager

Namespace automatically detects the package manager from their signature lock file. The following package managers are supported:

  • npm
  • yarn (v1 and v3)
  • pnpm

Existing configuration: package.json

Namespace builds the image using a layer-efficient way: first copies the package.json file to the container and runs the package manager to install the dependencies; then copies the rest of the source code. Further steps depend on the environment.

dev environment

  • NODE_ENV is set to development.
  • The dev script from package.json is used as the entry point of the container.

prod/test environment

  • NODE_ENV is set to development for test, production for prod.
  • The build script package.json is executed (if exists).
  • The start script from package.json is used as the entry point of the container.

Hybrid mode (server + browser)

Some frameworks (for example, Next.js) allow to run the same code in the browser and on the server. This is supported with the following caveats:

  • The user code has access to the runtime config only when running on the server.
  • The generated backends.ns.js file is available everywhere, but the addresses in the dev environment are only resolvable from the developer workstation and not from within the cluster (i.e. not from the server).

web

In the dev environment, the web integration is identical to the nodejs one: the dev script is executed at runtime, running vite or any other development server with hot-reload.

In prod/test, the code is built using the build script and served statically. The dist directory (by default, can be customized) is copied to the container and served using the nginx web server. This requires explicitly specifying which service correspond to the web server so the serving port is consistent between dev and prod.

See the syntax example.

Backends

The code that runs in the browser needs to be able to communicate with servers in the stack, but it doesn't have access to the runtime config (it is a Kubernetes mount). To solve this, Namespace generates a src/config/backends.ns.js file that contains the URLs of the requested servers in the stack and adds it to the built image. These URLs are accessible from the browser in all environments. The backends need to be explicitly specified in the web integration definition:

backends: {
  // "api" is an alias to access this specific backend in the frontend code.
  "api": "namespacelabs.dev/examples/multitier/01-simple/apibackend:webapi"
}