Node Actions

Node actions are like regular actions, but they are executed in the Node.js runtime, so their handlers can use Node’s built-in modules and npm packages that depend on them. You declare a node action group by building its spec with GroupSpec.makeNode() (rather than GroupSpec.make()); that marks the group as Node-runtime, and Confect adds Convex’s "use node" directive to the generated module accordingly. A node action group is otherwise an ordinary group—the same colocated .spec.ts/.impl.ts files, following the same naming and nesting conventions.

Node Spec

A node spec uses GroupSpec.makeNode() and one of FunctionSpec.publicNodeAction() or FunctionSpec.internalNodeAction() to define functions.

confect/email.spec.ts

import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

export default GroupSpec.makeNode().addFunction(
  FunctionSpec.publicNodeAction({
    name: "send",
    args: () => ({
      to: Schema.String,
      subject: Schema.String,
      body: Schema.String,
    }),
    returns: () => Schema.Null,
  }),
);

Node Impl

A node impl default-imports its sibling spec and passes the database schema from _generated/schema to FunctionImpl.make and GroupImpl.make—exactly like a non-node impl; only the spec differs (GroupSpec.makeNode()). Each handler runs in the Node.js runtime, so it has access to NodeServices from the @effect/platform-node package (filesystem, path, child processes, and more).

confect/email.impl.ts

import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Console from "effect/Console";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as ChildProcess from "effect/unstable/process/ChildProcess";
import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
import databaseSchema from "./_generated/schema";
import email from "./email.spec";

const send = FunctionImpl.make(
  databaseSchema,
  email,
  "send",
  Effect.fn(function* ({ to, subject, body }) {
    const spawner = yield* ChildProcessSpawner;
    const result = yield* spawner
      .string(
        ChildProcess.make("echo", [
          `Sending email to ${to} with subject ${subject} and body ${body}…`,
        ]),
      )
      .pipe(Effect.orDie);

    yield* Console.log(result);
    yield* Effect.sleep(Duration.seconds(1));
    yield* Console.log("Email sent!");

    return null;
  }),
);

export default GroupImpl.make(databaseSchema, email).pipe(
  Layer.provide(send),
  GroupImpl.finalize,
);

Calling Node Actions

Node actions are referenced like any other function. A node group at confect/email.spec.ts is reached at refs.public.email.

import { useAction } from "@confect/react";
import refs from "../confect/_generated/refs";

const sendEmail = useAction(refs.public.email.send);

sendEmail({
  to: "user@example.com",
  subject: "Hello",
  body: "Hello from Confect!",
});

Getting Started

Concepts

Server

Clients

Guides

Node Spec

Node Impl

Calling Node Actions

​Node Spec

​Node Impl

​Calling Node Actions

Node Spec

Node Impl

Calling Node Actions