@nmtjs/nuxt

NeemataJS

Neem hosting and durable workflows. Applications own their RPC, HTTP and clients; Neemata supervises their processes and coordinates their durable work.

@nmtjs/workflows, @nmtjs/effect and @nmtjs/pubsub require Effect 4 (effect@^4.0.4).

Workflows with typed steps

Tasks and workflows are declared once, with effect/Schema schemas and Effect handlers. A workflow's body is a generator: each w.* step returns a reference to its output that later steps read, and every task and workflow names the execution pool it runs on:

// workflow.ts
import { task, workflow } from '@nmtjs/workflows'
import * as Effect from 'effect/Effect'
import * as Schema from 'effect/Schema'

export const Normalize = task({
  name: 'normalize',
  pool: 'default',
  input: Schema.String,
  output: Schema.String,
  handler: (text) => Effect.succeed(text.trim().toLowerCase()),
})

export const WordCount = workflow(
  {
    name: 'word-count',
    pool: 'default',
    input: Schema.String,
    output: Schema.Number,
  },
  function* (w) {
    const normalized = yield* w.task('normalized', Normalize, {
      input: w.input,
    })
    return yield* w.activity('counted', {
      input: Schema.String,
      output: Schema.Number,
      from: normalized,
      handler: (text) => Effect.succeed(text ? text.split(/\s+/).length : 0),
    })
  },
)

Client.start(WordCount, 'Hello world') starts a run; Worker.coordinator and Worker.execution serve WordCount.workflows and WordCount.tasks. Graphs also support branches, parallel steps, child workflows and bounded fan-out with mapTask / mapWorkflow. Runs live in an in-memory, PostgreSQL or Redis store, and failed runs can be retried while keeping the steps that succeeded.

Neem CLI

neem build compiles config, app entries, plugin entries, and plugin-declared artifacts into the config's outDir, resolved from the config file (default dist). It writes an internal neem.manifest.json with relative artifact paths.

neem start consumes an existing built output directory: dist by default, or the outDir of the config passed with --config. It reads the manifest for executable artifacts and serialized runtime config, registers built plugin hooks, and starts app workers in production mode.

neem dev uses .neem/<config name> next to the config (e.g. .neem/neem.config) as a build-like watched output directory, so several configs in one package keep separate dev output. --outDir, resolved from the working directory, overrides the output directory of every command. It uses the same manifest shape as start, restarts app workers after successful config/app rebuilds, reloads plugin hooks after plugin entry rebuilds, and keeps existing workers alive on rebuild errors.

neem preview builds production artifacts with source maps into .neem/preview/<config name> (never the config's outDir), then serves them as neem start would. The build runs in a separate process that exits before serving, and a failed build never starts earlier output. See Preview.

Worker edits restart runtimes within their existing threads, with fresh-bundle thread restarts when needed; see Runtime restart.

Use neem dev --env-files ../../.env to load environment variables before config evaluation and worker startup. See development environment files for precedence and multiple-file usage.

Workspace development

Use Node.js 24 through vp and pnpm. Proxy work also needs a stable Rust toolchain with rustfmt and clippy, a C/C++ toolchain, CMake, and pkg-config. On macOS, install the Xcode command-line tools first.

vp env exec pnpm install
vp env exec pnpm build
vp env exec pnpm test --reporter=agent
vp env exec pnpm check

The workspace type-checks and builds with tsrs, a Rust port of TypeScript 7, and does not install the typescript package. Editors set to use the workspace TypeScript version fall back to their bundled one; point yours at tsrs --lsp to get the same checker as pnpm check.

The stack installs @nmtjs/proxy from npm at the version pinned in packages/neem/package.json, so pnpm build, pnpm test and pnpm check need no Rust toolchain. pnpm test:proxy runs the Rust and proxy integration suites and builds a local debug binding; set NEEM_INTERNAL_PROXY_MODULE to the absolute path of packages/proxy/dist/index.js (for example $PWD/packages/proxy/dist/index.js from the workspace root) to run Neem against it. CI does the same in the Test proxy workflow, which runs only when packages/proxy changes. pnpm test:prom-client runs the prom-client Vitest project, which the root Vitest run also includes.

Package versions are committed and bumped by hand in pull requests. The eight stack packages (common, effect, metrics, neem, nuxt, pubsub, vite, workflows) share one version: pnpm run version:stack <version> sets it on all of them. Proxy and prom-client are versioned independently; bump and release them before a stack release that needs the new version; after a proxy release, update the pinned version and peer range in packages/neem/package.json. After the bump is merged, dispatch the matching workflow: Publish Neem stack, Publish proxy or Publish prom-client. Each one reads the committed version and fails early if it is already on npm. The stack workflow also fails if the stack versions differ, or if the committed proxy or prom-client version has not been published yet. All three workflows share one publishing queue, so releases run one at a time across packages and branches.

Stack packages depend on each other with workspace:*, which publishes exact versions. They depend on prom-client with workspace:^ and on proxy through a caret peer range, so both can be upgraded without a stack release. Proxy releases build all seven native targets, generate the platform packages from packages/proxy/package.json, and publish them with napi pre-publish before publishing the wrapper. Generated packages/proxy/npm/ directories are ignored and are not workspace members. Git tags are v<version> for the stack, proxy-v<version> for proxy, and prom-client-v<version> for prom-client.

Package-specific READMEs and licenses are retained; prom-client remains Apache-2.0 and includes its upstream notices. Configure npm publishing access for publish-proxy.yml on proxy and its platform packages, and for publish-prom-client.yml on prom-client. Stack packages use publish.yml.

Service integration tests

Service-backed integration tests live beside package owners under packages/*/tests/integration.

docker compose up -d --wait redis valkey postgres
NMTJS_REQUIRE_SERVICE_TESTS=1 \
REDIS_URL=redis://localhost:6379 \
VALKEY_URL=redis://localhost:6380 \
POSTGRES_URL=postgres://neemata:neemata@localhost:5432/neemata \
pnpm run test:integration:services

Without service env, these tests skip in normal package/root test runs. In CI, NMTJS_REQUIRE_SERVICE_TESTS=1 makes missing service env fail instead of skip.