> ## Documentation Index
> Fetch the complete documentation index at: https://docs.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# package.json Standards for Figentra Monorepo Packages

> A complete guide to required package.json fields, scripts, exports configuration, and versioning rules for Figentra monorepo packages.

In a monorepo, `package.json` is more than a dependency manifest — it is the contract between your package and every consumer, whether that consumer is another internal package or an external developer. Standardising the fields, scripts, and export map across every Figentra package means that build tooling, release automation, and IDE tooling can make reliable assumptions without per-package configuration.

## Required Fields

Every package under `packages/` must include the following `package.json` structure. Copy this as your starting point and replace the placeholder values:

```json package.json theme={null}
{
  "name": "@your-org/my-package",
  "version": "0.1.0",
  "description": "One-line package description",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "oxlint src",
    "typecheck": "tsc --noEmit"
  },
  "files": [
    "dist"
  ],
  "devDependencies": {
    "typescript": "^5.0.0",
    "vitest": "^1.0.0",
    "tsup": "^8.0.0",
    "oxlint": "^0.4.0"
  }
}
```

<Note>
  The `"files"` field restricts what gets published to the registry. Always set it to `["dist"]` so consumers never receive your source TypeScript, test files, or configuration files.
</Note>

## Scripts Convention

Every package must implement the following scripts. Add package-specific scripts alongside them, but do not rename or repurpose these standard entries:

| Script       | Purpose                                                  |
| ------------ | -------------------------------------------------------- |
| `build`      | Compile TypeScript to `dist/` using `tsup`               |
| `test`       | Run the full test suite once with Vitest                 |
| `test:watch` | Run tests in watch mode during development               |
| `lint`       | Run Oxlint against the `src/` directory                  |
| `typecheck`  | Run `tsc --noEmit` to check types without emitting files |

## The Exports Field

The `exports` field is **required** for all Figentra packages. It replaces the legacy `main` and `module` fields for modern tooling and gives you explicit control over what consumers can import.

```json package.json theme={null}
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
```

Using `exports` achieves three things:

1. **Dual ESM / CJS publishing** — bundlers that understand ESM receive the `.mjs` file; older CommonJS consumers receive the `.js` file.
2. **Type resolution** — TypeScript resolves the correct `.d.ts` declaration file for each format.
3. **Subpath control** — you can expose additional entry points (e.g., `"./testing"`) or block deep imports into `dist/` that consumers should not rely on.

## Versioning

<Steps>
  <Step title="Follow semantic versioning">
    All `@figentra/*` packages follow [semver](https://semver.org). A breaking change in a public API requires a major version bump. New backward-compatible features require a minor bump. Bug fixes require a patch bump.
  </Step>

  <Step title="Version packages together">
    All packages in the `@figentra/*` scope are versioned in lockstep. Do not manually bump version numbers — version increments are computed automatically from your commit messages using conventional commits.
  </Step>

  <Step title="Start at 0.1.0">
    New packages start at `0.1.0`. A `0.x` version signals that the public API may still change without a major version bump — useful during the initial development period before a package is considered stable.
  </Step>
</Steps>

## Do Not Commit dist/

<Warning>
  Never commit the `dist/` directory to git. Add it to your `.gitignore` at the package level or monorepo root.

  ```text .gitignore theme={null}
  dist/
  *.tsbuildinfo
  ```

  The `dist/` output is a build artifact. It is generated by CI during the release process and published directly to the registry from the pipeline — not from your local machine.
</Warning>