# NPM scripts

> NPM scripts for building, serving, validating, and maintaining the OpenTelemetry website.

---

Site [llms.txt](/llms.txt)

---

Script definitions live in the repository root [`package.json`][]. To run a
script, use `npm run` _`SCRIPT_NAME`_.

## Nomenclature

- **Internal scripts**
  - Names starting with `_` are internal helpers and are not intended to be run
    directly.
  - So are `NAME::pre` and `NAME::post` scripts, the explicitly called pre and
    post steps of `NAME`.
- **Default vs `:all` script variants**
  - The **`check`**, **`fix`**, and **`test`** scripts run the most commonly
    needed subscripts for each action.
  - The **`*:all`** variants `check:all`, `fix:all`, and `test:all` run wider
    subscript sets; each variant's table entry states its scope.

## Installing and updating dependencies

| Script            | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `ci:min`          | [Lock-exact inert install][] for CI: no lifecycle scripts.                           |
| `ci:prepare`      | Post-`ci:min` setup: [fetch the pinned Hugo binary][], then `prepare`.               |
| `install:safe`    | [Lock-exact local setup][]: inert install, then `ci:prepare`.                        |
| `prepare`         | Install step: `get:submodule`, then Docsy's [lock-exact theme dependency install][]. |
| `update:hugo`     | Install latest hugo-extended, scripts enabled; the [Hugo bump][] lists the steps.    |
| `update:packages` | Run npm-check-updates to bump deps, subject to the [release cooldown][].             |

## Build and serve

| Script             | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `build:full`       | Build the full site. For details, see [Build kinds][].         |
| `build:lean`       | Do a lean build of the site. For details, see [Build kinds][]. |
| `build:preview`    | Full build with minification (e.g. for Netlify preview).       |
| `build:production` | Production Hugo build with minification.                       |
| `build`            | Build the site. Defaults to lean; see [Build kinds][].         |
| `clean`            | Run `make clean`.                                              |
| `serve:hugo`       | Start Hugo server with in-memory render.                       |
| `serve`            | Start Hugo dev server (default; full render).                  |

To build or serve the site with [website telemetry][], set the `SITE_NAME`
environment variable to `opentelemetry`; your local browsing then exports spans
to the project collector, as production does:

```sh
SITE_NAME=opentelemetry npm run serve
```

Prefer a full build over a [lean][build kinds] one when comparing telemetry with
production's: shared chrome changes what the page fetches, so a lean build's
telemetry differs.

## Checking

| Script                            | Description                                                                 |
| --------------------------------- | --------------------------------------------------------------------------- |
| `check:all`                       | Run all check scripts in sequence.                                          |
| `check:code-excerpts`             | Check code excerpts, fail if updates needed.                                |
| `check:codeowners`                | Verify CODEOWNERS locale section matches the registry.                      |
| `check:collector-sync`            | Run collector-sync checks.                                                  |
| `check:expired`                   | List expired content (by front matter).                                     |
| `check:filenames`                 | [Validate file naming & detect obsolete files/folders][fn].                 |
| `check:format`                    | Prettier and prose-wrap checks.                                             |
| `check:i18n`                      | Validate localization front matter (`default_lang_commit`).                 |
| `check:l10n`                      | Run localization checks.                                                    |
| `check:links:internal`            | Offline link check (internal links only); lean build first.                 |
| `check:links:production-internal` | [Offline check of internal links over a lean production build][prod-check]. |
| `check:links`                     | [Link check][] with Lychee; lean build first.                               |
| `check:markdown:specs`            | Markdown lint for spec fragments in `tmp/`.                                 |
| `check:markdown`                  | Markdown lint (content and projects).                                       |
| `check:spelling`                  | cspell over content, data, and layout Markdown.                             |
| `check:text`                      | textlint over content and data.                                             |
| `check`                           | Run the most commonly needed check scripts in sequence.                     |

## Fixing

| Script                        | Description                                                    |
| ----------------------------- | -------------------------------------------------------------- |
| `fix`                         | Run the most commonly needed fix scripts.                      |
| `fix:code-excerpts`           | Refresh code excerpts.                                         |
| `fix:codeowners`              | Regenerate CODEOWNERS locale section from the registry.        |
| `fix:all`                     | Run all fix scripts.                                           |
| `fix:format`                  | Apply Prettier and trim trailing spaces.                       |
| `fix:format:staged`           | Format only staged files.                                      |
| `fix:i18n`                    | Add/fix i18n front matter (`fix:i18n:new`, `fix:i18n:status`). |
| `fix:l10n`                    | Apply localization fixes.                                      |
| `fix:link-cache`              | Check links, updating the committed [`link-cache.jsonc`][].    |
| `fix:link-cache:double-check` | [Re-verify failing links with the browser probe][dc].          |
| `fix:link-cache:refresh`      | Prune the oldest cache entries, then `fix:link-cache`.         |
| `fix:markdown`                | Fix Markdown lint issues and trailing spaces.                  |
| `fix:submodule`               | Update, re-pin, and list submodule revisions.                  |
| `fix:filenames`               | [Rename files & remove obsolete files/folders][fn].            |
| `fix:dict`                    | Sort cspell word lists and normalize front matter.             |
| `fix:expired`                 | Delete files reported by `check:expired`.                      |
| `fix:text`                    | Run textlint with --fix.                                       |
| `fix:collector-sync:lint`     | Run ruff with --fix in collector-sync.                         |
| `format`                      | Alias for Prettier write (content and nowrap paths).           |

## Submodules and content

| Script             | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `code-excerpts`    | Refresh code excerpts. DEPRECATED: use `fix:code-excerpts` or `check:code-excerpts`. |
| `cp:spec`          | Copy spec content (content-modules).                                                 |
| `get:submodule`    | Init/update git submodules (set `GET=no` to skip).                                   |
| `pin:submodule`    | Pin submodule revisions (optional `PIN_SKIP`).                                       |
| `schemas:update`   | Update OpenTelemetry spec submodule and content.                                     |
| `update:submodule` | Update submodules to latest remote and fetch tags.                                   |

## Test and CI

| Script                     | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `diff:check`               | Warn if working tree has uncommitted changes.                               |
| `diff:fail`                | Fail if working tree has changes (e.g. after build).                        |
| `fix-and-test:all`         | All fixes (incl. i18n), then checks; links checked once.[^fat]              |
| `is:clean`                 | Fail if the Git working tree has changes, including untracked files.        |
| `netlify-build:preview`    | Build the Netlify deploy preview.                                           |
| `netlify-build:production` | Build the Netlify production site.                                          |
| `test-and-fix`             | Run fix scripts (excluding i18n/link-cache/submodule), then checks.         |
| `test:all`                 | Runs `test:base` then `test:compound-tests`.                                |
| `test:base`                | Base tests (same as `check`).                                               |
| `test:collector-sync`      | Collector-sync tests.                                                       |
| `test:compound-tests`      | Runs compound `test:*-*` scripts.[^categories]                              |
| `test:double-check:live`   | Live smoke check of the [double-check probe][dc].                           |
| `test:edge-functions:live` | Optional `node:test` live suite; supports `--help`.                         |
| `test:edge-functions`      | Node test runner over `netlify/edge-functions/**/*.test.ts`.                |
| `test:local-tools`         | Node test runner for `scripts/**/*.test.mjs`.[^categories]                  |
| `test:local-tools:lychee`  | Lychee-binary slice of `test:local-tools`; skips when the binary is absent. |
| `test:public`              | Runs the `tests/public/` checks over the built site.[^categories]           |
| `test`                     | Run the most commonly needed tests.                                         |

[^categories]:
    These scripts follow the test-script naming conventions; see
    [Test categories](../../testing/#test-categories).

[^fat]:
    The housekeeping default: runs `fix:link-cache` (link check, refreshing the
    link cache) after the content fixes; uses the keep-going `all` runner so
    every fix is captured. The check phase excludes `check:links`
    (`fix:link-cache` covers it) and `check:i18n` (redundant after `fix:i18n`
    records drift status). See [Housekeeping](../ci-workflows/#housekeeping).

## Utilities

| Script                         | Description                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `all`                          | Run all given scripts, even when some fail; exit non-zero if any failed.          |
| `generate:config:links`        | Generate git-ignored `lychee.toml` from `lychee.base.toml` + page front matter.   |
| `link-cache`                   | Inspect or prune the committed [`link-cache.jsonc`][] (`-- --help`).              |
| `locale-auto-merge`            | [Locale auto-merge helper CLI][locale-auto-merge] (`--help`).                     |
| `log:build`, `log:check:links` | Run corresponding script, tee output to `tmp/`, propagate the script's exit code. |
| `seq`                          | Run given script names in sequence; exit on first failure.                        |

<!-- prettier-ignore-start -->
[`link-cache.jsonc`]: ../link-checking/#link-cache
[`package.json`]: https://github.com/open-telemetry/opentelemetry.io/blob/main/package.json
[build kinds]: ../#build-kinds
[dc]: ../link-checking/#double-check
[fetch the pinned Hugo binary]: ../dependencies/#install-contracts
[fn]: /docs/contributing/pr-checks/#filename-check
[Hugo bump]: ../dependencies/#hugo
[link check]: ../link-checking/
[locale-auto-merge]: ../ci-workflows/#locale-auto-merge
[lock-exact inert install]: ../dependencies/#install-contracts
[lock-exact local setup]: ../dependencies/#install-contracts
[lock-exact theme dependency install]: ../dependencies/#install-contracts
[prod-check]: ../link-checking/#production-internal
[release cooldown]: ../dependencies/#release-cooldown
[website telemetry]: ../../features/#website-telemetry
<!-- prettier-ignore-end -->