CORE CONCEPTS

Config & Build

defineConfig() is a typed pass-through helper for your rasengan.server.ts file, read by both the CLI and bootstrap().

rasengan.server.ts
import { defineConfig } from '@rasenganjs/server';
 
export default defineConfig({
  entry: 'src/main.ts',
  port: 4000,
  host: '0.0.0.0',
  preset: 'node',
  watchDir: 'src/',
  build: {
    outDir: 'dist',
    minify: true,
    formats: ['single-file'],
  },
});

RasenganServerConfig

OptionTypeDefaultDescription
entrystring"src/main.ts"Path to the server entry file
portnumber3000Port the server listens on
hoststring"0.0.0.0"Host address to bind to
preset'node' | 'bun' | 'workerd'"node"Target runtime
watchDirstring | string[]"src/"Directory(ies) watched in dev mode
buildBuildConfigsee belowProduction build output options

BuildConfig

OptionTypeDefaultDescription
outDirstring"dist"Output directory
minifybooleantrueMinify the bundled output
formatsArray<'single-file' | 'directory'>['directory']Output format(s) to produce

Resolution Order

Configuration merges from four sources, later ones winning:

  1. Built-in defaults (the table above).
  2. rasengan.server.js or rasengan.server.ts at the project root. .env* files are already loaded by this point, so this file can read process.env itself (see Environment Variables).
  3. PORT/HOST environment variables, for port/host specifically.
  4. CLI flag overrides (--port, --host, --entry, --preset, --watch-dir), see CLI.

Build Output Formats

rasengan-server build bundles your server with esbuild:

  • single-file: everything bundled into one server.bundle.mjs. Simplest to deploy, copy one file.
  • directory: one .mjs per source file, preserving your project's structure. Useful when you want to inspect or patch individual output files.

Both formats can be produced in the same build by listing both in formats.

Programmatic Overrides

bootstrap() accepts an optional second argument, a partial config that merges on top of everything else, useful for tests or embedding:

Overriding config programmatically
bootstrap(
  (app) => {
    app.registerModule(appModule);
  },
  { port: 0 }
); // port 0 lets the OS assign a free port, handy in tests
Module Plugins
Environment Variables