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 { 
import NodeRuntime
NodeRuntime } from "@effect/platform-node"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3

4
const 
const success: Effect.Effect<string, never, never>
success = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const succeed: <string>(value: string) => Effect.Effect<string, never, never>
Creates an Effect that always succeeds with a given value.
When to Use
Use this function when you need an effect that completes successfully with a
specific value without any errors or external dependencies.
@see ― fail to create an effect that represents a failure.
@example 
// Title: Creating a Successful Effect
import { Effect } from "effect"

// Creating an effect that represents a successful scenario
//
//      ┌─── Effect<number, never, never>
//      ▼
const success = Effect.succeed(42)
@since ― 2.0.0
succeed("Hello, World!")
5

6
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<never, string>(effect: Effect.Effect<string, never, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const success: Effect.Effect<string, never, never>
success)
7
// No Output

Example (Running a Failing Program)

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

4
const 
const failure: Effect.Effect<never, string, never>
failure = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
Creates an Effect that represents a recoverable error.
When to Use
Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like
catchAll
or
catchTag
.
@see ― succeed to create an effect that represents a successful value.
@example 
// Title: Creating a Failed Effect
import { Effect } from "effect"

//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@since ― 2.0.0
fail("Uh oh!")
5

6
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<string, never>(effect: Effect.Effect<never, string, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const failure: Effect.Effect<never, string, never>
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 { 
import NodeRuntime
NodeRuntime } from "@effect/platform-node"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3

4
const 
const failure: Effect.Effect<never, string, never>
failure = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
Creates an Effect that represents a recoverable error.
When to Use
Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like
catchAll
or
catchTag
.
@see ― succeed to create an effect that represents a successful value.
@example 
// Title: Creating a Failed Effect
import { Effect } from "effect"

//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@since ― 2.0.0
fail("Uh oh!")
5

6
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<string, never>(effect: Effect.Effect<never, string, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const failure: Effect.Effect<never, string, never>
failure, { 
disablePrettyLogger?: boolean | undefined
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 { 
import NodeRuntime
NodeRuntime } from "@effect/platform-node"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3

4
const 
const failure: Effect.Effect<never, string, never>
failure = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
Creates an Effect that represents a recoverable error.
When to Use
Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like
catchAll
or
catchTag
.
@see ― succeed to create an effect that represents a successful value.
@example 
// Title: Creating a Failed Effect
import { Effect } from "effect"

//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@since ― 2.0.0
fail("Uh oh!")
5

6
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<string, never>(effect: Effect.Effect<never, string, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const failure: Effect.Effect<never, string, never>
failure, { 
disableErrorReporting?: boolean | undefined
disableErrorReporting: true })
7
// No Output

Example (Running a Failing Program With Custom Teardown)

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

4
const 
const failure: Effect.Effect<never, string, never>
failure = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
Creates an Effect that represents a recoverable error.
When to Use
Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like
catchAll
or
catchTag
.
@see ― succeed to create an effect that represents a successful value.
@example 
// Title: Creating a Failed Effect
import { Effect } from "effect"

//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@since ― 2.0.0
fail("Uh oh!")
5

6
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<string, never>(effect: Effect.Effect<never, string, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const failure: Effect.Effect<never, string, never>
failure, {
7
  
teardown?: Teardown | undefined
teardown: function 
function (local function) customTeardown<E, A>(exit: Exit<E, A>, onExit: (code: number) => void): void
customTeardown(
exit: Exit<E, A>
exit, 
onExit: (code: number) => void
onExit) {
8
    if (
exit: Exit<E, A>
exit.
_tag: "Success" | "Failure"
_tag === "Failure") {
9
      
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr
If formatting elements (e.g. %d) are not found in the first string then
util.inspect() is called on each argument and the
resulting string values are concatenated. See util.format()
for more information.
@since ― v0.1.100
error("Program ended with an error.")
10
      
onExit: (code: number) => void
onExit(1)
11
    } else {
12
      
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log("Program finished successfully.")
13
      
onExit: (code: number) => void
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
*/