---
title: ESM API
description: Use Presswork as an Effect service through its public ESM root export, with schemas, typed results, failures, and live Layer setup.
---

Presswork publishes one named ESM entry point from `presswork`. The public API exposes the `Presswork` Effect service, input and output schemas, and their TypeScript types. Package subpaths and workspace modules are not public API.

## Run a Check

Install Presswork and the compatible Effect release in an ESM project running Node.js 24 or later. The example imports both packages directly.

```sh
npm install presswork effect@4.0.0-rc.115
```

This example discovers the Repository Root from the current directory and runs a Check.

```js
import { Effect, Schema } from 'effect';
import { Presswork, RepositorySelection } from 'presswork';

const repository = Schema.decodeUnknownSync(RepositorySelection)({});

const report = await Effect.runPromise(
  Effect.gen(function* () {
    const presswork = yield* Presswork;
    return yield* presswork.check(repository);
  }).pipe(Effect.provide(Presswork.layer), Effect.scoped),
);

console.log(report);
```

`RepositorySelection` accepts an optional `root`. When it is omitted, Presswork discovers the Repository Root from the current directory. `Presswork.layer` supplies the live service implementation. The service methods return Effects with typed failure channels.

## `Presswork`

`Presswork` is an Effect `Context.Service`. Access it with `yield* Presswork` inside an Effect program and provide `Presswork.layer` at the application boundary.

| Method                          | Input                 | Success         | Failure                  |
| ------------------------------- | --------------------- | --------------- | ------------------------ |
| `check(repository)`             | `RepositorySelection` | `CheckReport`   | `CheckFailure`           |
| `listDocumentTypes(repository)` | `RepositorySelection` | `CreateCatalog` | `CheckFailure`           |
| `create(request)`               | `CreateRequest`       | `CreateOutcome` | `CreateFailure`          |
| `renderDocsSkill(repository)`   | `RepositorySelection` | `string`        | `RenderSkillDocsFailure` |

`check` is read-only. `create` can initialize a Document Draft and update its Index Document according to the selected Document Type and Creation Policy. `renderDocsSkill` returns the complete generated `SKILL.md` content as a string.

## Inputs

Use the exported Effect schemas to decode unknown values before passing them to the service.

| Input                           | Field          | Type                        | Required | Meaning                                |
| ------------------------------- | -------------- | --------------------------- | -------- | -------------------------------------- |
| `RepositorySelection`           | `root`         | `string`                    | No       | An explicit Repository Root selection. |
| `CreateRequestSchema`           | `documentType` | `DocumentTypeId`            | Yes      | The Document Type to create.           |
| `CreateRequestSchema`           | `fields`       | `DocumentFieldAssignment[]` | Yes      | Field values used to render the draft. |
| `CreateRequestSchema`           | `repository`   | `RepositorySelection`       | Yes      | The Repository Root selection.         |
| `DocumentFieldAssignmentSchema` | `name`         | `DocumentFieldName`         | Yes      | The configured field name.             |
| `DocumentFieldAssignmentSchema` | `value`        | `string`                    | Yes      | The field value.                       |

`DocumentTypeId` is a branded schema for a lower-case identifier. `DocumentFieldName` is a branded string schema. The matching TypeScript exports are `CreateRequest` and `DocumentFieldAssignment`.

## Results

`check` returns `CheckReport`. See [Check Report](/check-report/) for its complete and incomplete variants, fields, Violations, and Operational Diagnostics.

`listDocumentTypes` returns `CreateCatalog` through `CreateCatalogSchema`.

| Field                              | Type                                 | Required | Meaning                                       |
| ---------------------------------- | ------------------------------------ | -------- | --------------------------------------------- |
| `repositoryRoot`                   | `string`                             | Yes      | The selected absolute Repository Root.        |
| `documentTypes`                    | array                                | Yes      | The configured Document Types.                |
| `documentTypes[].documentType`     | `DocumentTypeId`                     | Yes      | The Document Type identifier.                 |
| `documentTypes[].creationPolicy`   | `external`, `manual`, or `presswork` | Yes      | The owner of Document Creation.               |
| `documentTypes[].externalWorkflow` | `string`                             | No       | The configured external workflow, if present. |

`create` returns `CreateOutcome` through `CreateOutcomeSchema`.

| Field                 | Type           | Meaning                                                      |
| --------------------- | -------------- | ------------------------------------------------------------ |
| `createdPath`         | `string`       | The created repository-relative path.                        |
| `updatedIndex`        | `string`       | The updated repository-relative Index Document path.         |
| `draftStatus`         | `"unfinished"` | The fixed status of a newly initialized Document Draft.      |
| `pendingRequirements` | `string[]`     | Template requirements that remain for the author to resolve. |

`renderDocsSkill` returns the generated `SKILL.md` as a `string`.

The root API also exports `OperationalDiagnosticSchema`, `DocumentDiscoveryDiagnosticSchema`, and `DocumentEvaluationDiagnosticSchema` with their matching TypeScript types. Their fields and conditions are documented with the [Check Report Operational Diagnostics](/check-report/#operational-diagnostics).

## Failure types

The root entry point exports `CheckFailure`, `CreateFailure`, `RenderSkillDocsFailure`, and their combined `CommandFailure` union. Failures remain in the Effect error channel.

Repository and configuration failures apply to all four methods.

| `_tag`                           | Additional fields                      | Condition                                                 |
| -------------------------------- | -------------------------------------- | --------------------------------------------------------- |
| `RepositoryRootNotFoundError`    | `message`, `path`, `recovery`          | Repository Root discovery found no valid root.            |
| `InvalidRepositoryRootError`     | `message`, `path`, `recovery`          | An explicit root is not a valid Repository Root.          |
| `RepositoryRootUnavailableError` | `cause`, `message`, `path`, `recovery` | Presswork could not inspect the selected Repository Root. |
| `ConfigurationUnavailableError`  | `cause`, `message`, `path`, `recovery` | Present Presswork Configuration could not be read.        |
| `InvalidConfigurationError`      | `message`, `path`, `recovery`          | Present Presswork Configuration is invalid.               |

`create` can also fail with `_tag: "DocumentCreationError"`. It has `code`, `message`, and `recovery`, with optional `path` and `cause` fields.

| `code`                                | Condition                                                     |
| ------------------------------------- | ------------------------------------------------------------- |
| `document-type-unknown`               | The requested Document Type is not configured.                |
| `document-type-creation-external`     | An external workflow owns creation.                           |
| `document-type-creation-manual`       | The Document Type requires manual creation.                   |
| `document-creation-field-invalid`     | A field name or value does not satisfy the Document Type.     |
| `document-creation-preflight-failed`  | Template, index, or mutation preflight failed.                |
| `document-creation-conflict`          | An existing destination or another writer prevented creation. |
| `document-creation-index-stale`       | The Index Document changed before publication.                |
| `document-creation-recovery-required` | The Index update failed after the draft was preserved.        |
| `document-creation-unavailable`       | A required Template or filesystem operation was unavailable.  |

`renderDocsSkill` can also fail with `_tag: "SkillDocsError"`. It has `code`, `message`, and `recovery`, with an optional `path`.

| `code`                           | Condition                                                    |
| -------------------------------- | ------------------------------------------------------------ |
| `document-discovery-unavailable` | Document discovery could not complete.                       |
| `document-read-unavailable`      | A Recognized Document could not be read.                     |
| `target-inspection-unavailable`  | A local Markdown target could not be inspected.              |
| `skill-guidance-unavailable`     | Required Template or Document Type guidance was unavailable. |

Use Effect error operators to inspect or recover from these failures before running the program when your application needs custom handling.

Use the [CLI reference](/cli/) for process behavior and the [Check Report reference](/check-report/) for the report fields and semantics.