Backend Projects

Backend projects usually use one of two patterns:

cnos run -- <command> for zero-code-change adoption
import cnos from '@kitsy/cnos' for direct runtime reads

For an existing Express or Node service that already uses .env, start with the env bridge:

cnos build env --profile local --to .env.local
cnos build env --profile stage --to .env.stage

Then keep your current dotenv setup while moving runtime reads to CNOS.

Example:

import cnos from '@kitsy/cnos';

await cnos.ready();

const port = cnos.value('server.port');
const token = cnos.secret('app.token');

Derived server config stays inside CNOS too:

server:
  effective_port:
    $derive:
      expr: "coalesce(process.env.PORT, value.server.default_port, '3000')"

const port = cnos.value('server.effective_port');

If you need live request or session context, declare a runtime namespace and register a provider:

cnos.registerRuntimeProvider('request', (key) => {
  if (key === 'headers.host') {
    return currentRequest?.headers.host;
  }

  return undefined;
});

Env export bridge:

cnos build env --to .env.local
cnos build env --profile stage --to .env.stage

Projection-first packaging:

cnos build server --profile prod --to .cnos-server.json