# Local Development

## Install

Follow the authentication setup in [Installation](../getting-started/installation.md), then install dependencies:

```bash
npm install
```

To develop against a local checkout of the core library, link it after installation:

```bash
npm link ../core-library
```

Replace the example with the actual path. `package.json` keeps the published range `"@bayudwiyansatria/core": "^1.2.1"`;
the link only changes `node_modules`. Running `npm install` replaces the symlink, so link it again afterward. Rebuild
the linked library before testing changes here.

## Commands

| Command                       | Purpose                                                        |
| ----------------------------- | -------------------------------------------------------------- |
| `npm run build`               | Build both package entries into `lib/`                         |
| `npm run dev`                 | Rebuild both entries on file changes                           |
| `npm test`                    | Run lint, Markdown checks, and Jest                            |
| `npm run test:run`            | Run Jest with coverage under `dist/coverage/`                  |
| `npm run lint:run`            | Lint `src/`                                                    |
| `npm run lint:fix`            | Lint `src/` and apply safe fixes                               |
| `npm run format`              | Format source and configuration files                          |
| `npm run format:docs`         | Format Markdown files                                          |
| `npm run format:docs:check`   | Check Markdown formatting                                      |
| `npm run docs:check`          | Check local Markdown links and anchors                         |
| `npm run build:docs`          | Generate TypeDoc output under `dist/docs/`                     |
| `npm run build:docs:book`     | Generate the HonKit book under `dist/book/`                    |
| `npm run build:docs:coverage` | Run tests to generate the documentation site's coverage report |
| `npm run build:static`        | Assemble the landing page, API docs, book, and coverage        |
| `npm run build:all`           | Build the package and all static documentation                 |
| `npm run docker:build:docs`   | Build the documentation site image                             |
| `npm run docker:serve:docs`   | Serve the documentation site at `http://localhost/`            |

## Build

```bash
npm run build
```

The main entry produces `lib/index.min.cjs`, `lib/index.min.mjs`, and `lib/index.d.ts`. The middleware entry produces
`lib/middlewares.min.cjs`, `lib/middlewares.min.mjs`, and `lib/middlewares.d.ts`. Source maps are written beside the
JavaScript bundles. There is no UMD bundle or declaration source map. The generated `lib/` directory is not committed.

Use `npm run dev` while iterating.

## Test

```bash
npm run test:run
```

Jest runs every `*.spec.ts` under `test/`, collects coverage from `src/**`, and writes LCOV and HTML reports to
`dist/coverage/`. The suite stops at the first failing test.

Run one file or matching test with:

```bash
npx jest --config jest.config.json test/core/bindings/Binding.spec.ts
npx jest --config jest.config.json -t 'rejects an empty name'
```

Tests use the same `@/` path mapping as the source through `moduleNameMapper` in `jest.config.json`.

## Lint and format

```bash
npm run lint
npm run format
npm run format:docs
```

ESLint uses the flat configuration in [`eslint.config.ts`](../../eslint.config.ts). It rejects unused variables and
enforces the package's import boundaries. See
[Module responsibility](../reference/directory-structure.md#module-responsibility) for the layer rules.

Prettier owns formatting. The project uses no semicolons, single quotes, a 120-column width, and two-space indentation.

## Type-check without building

```bash
npx tsc --noEmit
```

This is faster than a Rollup build when only type validation is needed.

## Documentation

```bash
npm run format:docs:check
npm run docs:check
npm run build:docs
npm run build:docs:book
```

The TypeDoc build fails on undocumented exports and invalid API cross-references. The Markdown checker validates local
file paths and heading anchors. See [Documentation](./documentation.md) for authoring conventions.

## Full static site

```bash
npm run build:static
```

This assembles the landing page, API reference, book, and coverage report in `dist/`. See [Docker](./docker.md) for
serving the result locally.