For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Layer composition makes dependencies explicit

A service is a named interface. A Layer describes how to build a service from other services. Choose and supply the services and their dependencies before running the application. Keep dependencies private unless callers need them too.¶

Supply dependencies without changing the domain

FileInspector.layer needs a filesystem implementation. NodeServices.layer supplies platform services. The CLI combines them before execution.¶

  Effect.provide(
    Layer.mergeAll(
      Layer.provideMerge(FileInspector.layer, NodeServices.layer),
      remoteJoinInterestLayer,
      Approval.denyAll
    )
  )
);

NodeRuntime.runMain(program);

Choose the combinator by the services the resulting Layer should expose:¶

Merging services does not, by itself, feed one Layer into another Layer’s requirements.¶

The test suite retains platform services with provideMerge because tests also create temporary files. Production callers that need only the inspector can keep its implementation dependency private with provide.¶

Reuse Layer identity when sharing construction

Sharing follows Layer identity within a build context that remembers which Layer values it has already constructed. Equivalent construction code does not make two Layer values identical. Sharing is limited to that construction context.¶

The fixture gives two consumers a resource. One case shares a Layer value; the other calls the Layer factory again.¶

      const resource = Resource.layer();

      const graph = Layer.merge(
        ReadAccess.layer.pipe(Layer.provide(resource)),
        WriteAccess.layer.pipe(
          Layer.provide(shared ? resource : Resource.layer())
        )
      );

Resource.layer() creates a new Layer value. Reusing resource lets the two branches share construction.¶

The fixture counts constructions and compares service ids:¶

      const ids = yield* Effect.gen(function* readServiceIds() {
        return [yield* ReadAccess, yield* WriteAccess];
      }).pipe(Effect.provide(graph));

      const count = yield* ConstructionCount;

      expect(yield* Ref.get(count)).toBe(constructions);
      expect(ids[0] === ids[1]).toBe(shared);

Independent application runtimes do not share instances merely because they import the same Layer value. Their construction context and memo-map lifetime matter too.¶

Common wrong approach

Calling a Layer factory twice can create two pools, caches, or background workers when one shared instance was intended. Keep the constructed Layer value and provide that same value to both consumers.¶

Do not use provideMerge everywhere to silence missing-service errors. Read which services callers need. Retaining every dependency exposes implementation details and makes removal harder.¶

Effect idiom and house rule

• Layers carry output services, construction failures, and input requirements. Composition resolves the requirements.¶
• In rat-stack, each entrypoint, where the application starts, chooses and supplies implementations in its composition root¹⁶.¶
• A cartridge³⁶ packages one job and its infrastructure. It must be removable without breaking unrelated packages.¶
• The application chooses its workspace layout and adapter package boundaries.¶

See also: service construction¹⁶, domain structure¹⁶, cartridges³⁶, and testing²².¶

Read why dependency injection matters¹⁴.¶

Last changed 2026-10-07 in e73c9d9. Source on GitHub. Change log.