Runtime

Running Your Main Program with runMain

runMain helps you execute a main effect with built-in error handling, logging, and signal management. You can concentrate on your effect while runMain looks after finalizing resources, logging errors, and setting exit codes.

• Exit Codes If your effect fails or is interrupted, runMain assigns a suitable exit code (for example, 1 for errors and 0 for success).
• Logs By default, it records errors. This can be turned off if needed.
• Pretty Logging By default, error messages are recorded using a “pretty” format. You can switch this off when required.
• Interrupt Handling If the application receives SIGINT (Ctrl+C) or a similar signal, runMain will interrupt the effect and still run any necessary teardown steps.
• Teardown Logic You can rely on the default teardown or define your own. The default sets an exit code of 1 for a non-interrupted failure.

Usage Options

When calling runMain, pass in a configuration object with these fields (all optional):

• disableErrorReporting: If true, errors are not automatically logged.
• disablePrettyLogger: If true, it avoids adding the “pretty” logger.
• teardown: Provide a custom function for finalizing the program. If missing, the default sets exit code 1 for a non-interrupted failure.

Example (Running a Successful Program)

1
import { NodeRuntime } from "@effect/platform-node"
2
import { Effect } from "effect"
3

4
const success = Effect.succeed("Hello, World!")
5

6
NodeRuntime.runMain(success)
7
// No Output

Example (Running a Failing Program)

1
import { NodeRuntime } from "@effect/platform-node"
2
import { Effect } from "effect"
3

4
const failure = Effect.fail("Uh oh!")
5

6
NodeRuntime.runMain(failure)
7
/*
8
Output:
9
[12:43:07.186] ERROR (#0):
10
  Error: Uh oh!
11
*/

Example (Running a Failing Program Without Pretty Logger)

1
import { NodeRuntime } from "@effect/platform-node"
2
import { Effect } from "effect"
3

4
const failure = Effect.fail("Uh oh!")
5

6
NodeRuntime.runMain(failure, { disablePrettyLogger: true })
7
/*
8
Output:
9
timestamp=2025-01-14T11:43:46.276Z level=ERROR fiber=#0 cause="Error: Uh oh!"
10
*/

Example (Running a Failing Program Without Error Reporting)

1
import { NodeRuntime } from "@effect/platform-node"
2
import { Effect } from "effect"
3

4
const failure = Effect.fail("Uh oh!")
5

6
NodeRuntime.runMain(failure, { disableErrorReporting: true })
7
// No Output

Example (Running a Failing Program With Custom Teardown)

1
import { NodeRuntime } from "@effect/platform-node"
2
import { Effect } from "effect"
3

4
const failure = Effect.fail("Uh oh!")
5

6
NodeRuntime.runMain(failure, {
7
  teardown: function customTeardown(exit, onExit) {
8
    if (exit._tag === "Failure") {
9
      console.error("Program ended with an error.")
10
      onExit(1)
11
    } else {
12
      console.log("Program finished successfully.")
13
      onExit(0)
14
    }
15
  },
16
})
17
/*
18
Output:
19
[12:46:39.871] ERROR (#0):
20
  Error: Uh oh!
21
Program ended with an error.
22
*/