# example-shared-package — `@ca/example-utils`

Complete minimal shared TypeScript package for a pnpm + Turborepo monorepo. Copy it as the
starting point for a new package and rename the scope to match your repository.

It goes under **`packages-backend/`** or **`packages-frontend/`** depending on who consumes
it — the root matches the consumers, never the author. See `references/packages.md` §1.

The package itself is environment-neutral: no Node built-ins, no DOM APIs. That is what makes
it a safe template for either root. Adding `fs`, `path`, or `crypto` makes it backend-only;
adding DOM APIs makes it frontend-only.

## Structure

```text
packages-backend/example-utils/        # or packages-frontend/example-utils/
├── .eslintrc.cjs
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts           # Public barrel — re-exports types and utils
    ├── types.ts           # Shared TypeScript types
    └── example-utils.ts   # Utility functions
```

## Key conventions

- `"type": "module"` with ESM output under `dist/`.
- `exports` maps the package root to `dist/index.js` and `dist/index.d.ts`.
- `tsconfig.json` extends the shared `typescript-config` preset — only `outDir` and `rootDir`
  are local.
- `.eslintrc.cjs` extends the shared `eslint-config` preset.
- Internal imports carry the `.js` extension — required for ESM TypeScript.
- `files: ["dist"]` keeps sources out of the published payload.
- Workspace dependencies use `workspace:*`.
- `src/index.ts` is the entire public API; nothing else is importable by consumers.
- Script names (`build`, `check-types`, `lint`) match the tasks in `turbo.json`, or Turborepo
  skips the workspace silently.

## Contract packages

A package that shares API types across the front/back boundary is a variant of this template:
name it `<domain>-contracts`, place it under `packages-backend/`, export **types only**, and
keep it free of runtime dependencies. Frontend consumers import it with `import type`.

## Validation commands

```bash
pnpm check-types --filter="@ca/example-utils"
pnpm lint        --filter="@ca/example-utils"
pnpm build       --filter="@ca/example-utils"
```