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
package.json
Existing configuration: 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 todevelopment
.- The
dev
script frompackage.json
is used as the entry point of the container.
prod
/test
environment
NODE_ENV
is set todevelopment
fortest
,production
forprod
.- The
build
scriptpackage.json
is executed (if exists). - The
start
script frompackage.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 thedev
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"
}