Collection of UXF command-line tools for CI pipelines and local project maintenance (releases, dependency checks, sitemap crawling, i18n namespace generation, dead-code detection, and more).
Reach for a specific binary from this package when you need one of the CI/maintenance tasks listed below. It is a CLI-only package — there is no importable API (main points to a non-existent index.js); consume it through its bin commands, not import/require.
Most binaries are already available in the UXF Docker images, so CI jobs can call them directly. Locally, run them with npx <command>.
yarn add -D @uxf/scriptsRequires Node.js >= 26 (engines.node). No peer dependencies. Runtime dependencies (cheerio, dayjs, fast-glob, got, rev-dep, robots-txt-parser, semver, yaml, yargs) are bundled.
Every command accepts -h / --help.
Reads commits on master since the last Git tag, generates release notes (grouped by conventional-commit type, linking YouTrack issues), creates a GitLab release, and posts a summary to Slack and/or Google Chat. Warns when the range contains DB migration files.
Without the options below it behaves as it always did. They let a project release from another branch under its own version tags and with notes written elsewhere (e.g. by Claude in an earlier job):
--ref – branch, tag or SHA to release from instead of master.--from – the range starts after this tag or SHA (GitLab compare) instead of the last tag with --tag-prefix.--tag – exact tag name (1.0.21) instead of <prefix><timestamp>. An existing tag is reused. When the release already exists, the run stops before sending anything, so a rerun neither announces the version twice nor overwrites notes edited by hand.--notes-file – Markdown used instead of the commit list, in the release as is and in the message converted to Google Chat formatting. The migration warning is still added.--fallback-note – put before the commit list when the notes file is missing or empty, so a failed notes job still ends in a release that says what to do.--no-release – send the message only, e.g. when deploying an already released version to production.--no-release-migration-warning – keep the DB migration warning in the message only, out of the release description, e.g. when the release is shown to end users.Usage:
uxf-release [options]
Environment variables:
GITLAB_TOKEN - required
CI_SERVER_URL - required - set by GitLab CI
CI_PROJECT_ID - required - set by GitLab CI
SLACK_TOKEN - optional
GOOGLE_WEBHOOK_URL - optional
Options:
-t, --tag-prefix Git tag prefix [string]
-g, --google-chat-webhook Google Chat webhook URL [string]
-m, --message Message title [string]
-p, --project-id GitLab project id (or use CI_PROJECT_ID) [number]
-s, --slack-channel Slack channel for notification [string]
--ref Branch, tag or SHA to release from (default: master)
--from Range start, tag or SHA (default: last prefixed tag)
--tag Exact tag name (default: prefix + timestamp)
--notes-file Markdown used instead of the commit list
--fallback-note Text before the commit list when notes are missing
--release Create the GitLab release; --no-release only notifies
--release-migration-warning Also in the release; --no-… keeps it in the message
-d, --dry-run Skip publishing and notifications [boolean]
-h, --help Show help [boolean]--project-id overrides CI_PROJECT_ID; --google-chat-webhook falls back to GOOGLE_WEBHOOK_URL.
.gitlab-ci.yml)Set GITLAB_TOKEN in the GitLab CI/CD variables, then:
# .gitlab-ci.yml
stages:
- release
release:
image: node:26
stage: release
before_script:
- npm install -g @uxf/scripts
script:
# ... deploy project ...
- uxf-release
Release cut on staging under a semver tag, with notes from an earlier job that is allowed to fail:
release:staging:
image: node:26
stage: deploy
when: always
script:
- npx -y -p @uxf/scripts uxf-release --ref "$CI_COMMIT_SHA" --from "$PREVIOUS_VERSION" --tag "$VERSION"
--notes-file release-notes.md --fallback-note "Release notes are missing, write them by hand."
--message "App $VERSION on staging"
Runs in GitLab CI. If the current commit is the merge commit of a merged MR, it posts a Google Chat message with the MR title, author, approver, and who merged it; otherwise it posts the list of pushed commits. Requires GITLAB_TOKEN plus the standard GitLab CI variables (CI_SERVER_URL, CI_PROJECT_ID, CI_COMMIT_SHA, CI_COMMIT_BEFORE_SHA, CI_COMMIT_REF_NAME).
Usage:
uxf-push-notifier [options]
Environment variables:
GITLAB_TOKEN - required
Options:
-g, --google-chat-webhook-url Target Google Chat webhook URL [string]
-h, --help Show help [boolean]stages:
- notify
notify-push:
image: node:26
stage: notify
except: [schedules]
only:
- develop # default branch
script:
- npm install -g @uxf/scripts
- uxf-push-notifier --google-chat-webhook-url=$GOOGLE_CHAT_WEBHOOK
All-in-one dependency health check for projects using @uxf/* packages. Runs two checks:
@uxf/* packages themselves resolve to different versions. Transitive-only duplicates (a dep pulled in by unrelated third-party packages at a different version) are ignored, since they don't affect @uxf/* compatibility.peerDependencies of installed @uxf/* packages are present and version-matched. react, react-dom and next are skipped, since a consumer always supplies those itself.The project's other direct dependencies are checked for missing required peers too. @apollo/client 4 requires rxjs, which a project usually has only because an unrelated package such as concurrently depends on it, until it stops. Optional peers are skipped, and a version outside a third-party peer range is not reported, since that is the project's call and --fix must not downgrade it. A missing peer is suggested and installed at the version already in the project's own node_modules when it satisfies the range, so the lock file keeps a single copy.
@uxf/* peers are checked like any other, and walked into: @uxf/ui peers @uxf/core-react, which peers @uxf/core, so a project listing only @uxf/ui is told to add all three. Neither yarn nor npm installs a peer of a peer, so without this the missing packages only show up as a build-time Cannot find module. The walk stops wherever a package is absent from node_modules, because its own peers cannot be read yet — --fix therefore installs what it found and repeats the collection until a pass adds nothing new.
A version mismatch on an @uxf/* package is reported but never auto-installed. Resolving a mismatch means installing name@expected, and for UXF packages that expected value is an exact pin taken from whichever package lags behind — so --fix would downgrade a package you bumped on purpose (@uxf/data-grid@11.129.0 pins @uxf/core@11.129.0, and a project on @uxf/core@11.131.0 would be pulled back). UXF packages move in lockstep, so the check points at yarn up "@uxf/*" instead. A missing @uxf/* package is still installed by --fix, since adding one cannot downgrade anything.
A dependency pinned to a source rather than a version (file:, link:, portal:, patch:, workspace:, an npm: alias, a git URL) has no version to compare, so it is listed under Overridden, so not version-checked and never counted as a mismatch — that is what keeps the file:../fe-monorepo/packages/<name> local-testing flow green. A yarn resolutions entry is invisible to the check either way, since only dependencies and devDependencies are read.
Supports yarn, npm, pnpm, and bun. The package manager is auto-detected from the lock file.
Usage:
uxf-dependencies-check [options]
Options:
--fix Auto-install missing/mismatched peer dependencies [boolean]
--dry-run Show what would be installed without changes [boolean]
-e, --exclude Packages to ignore in conflict check [array]
-h, --help Show help [boolean]Build-time dependencies (yargs, fast-glob) are automatically ignored in the conflict check.
# Run both checks (exits with code 1 if issues found)
npx uxf-dependencies-check
# Auto-install missing peer deps
npx uxf-dependencies-check --fix
# Preview what would be installed
npx uxf-dependencies-check --dry-run
# Ignore specific packages in conflict check
npx uxf-dependencies-check --exclude lodash dayjs
Transitive-only duplicates (caused by unrelated third-party packages, e.g. @udecode/plate-floating pulling an old @floating-ui/react alongside a newer one declared by an @uxf/* package) are filtered out automatically and do not need to be ignored.
For genuine declarer conflicts that you've consciously accepted — e.g. two @uxf/* packages that temporarily pin different versions of the same dep — each @uxf/* package can declare known conflicts in its own package.json:
{
"name": "@uxf/wysiwyg",
"uxf": {
"ignoredConflicts": ["some-shared-dep"]
}
}
Ignored conflicts are still printed as informational output but do not cause a non-zero exit code. The --exclude CLI flag hides packages completely (not printed at all).
yarn.lock / package-lock.json / pnpm-lock.yaml / bun.lock) to find dependencies with multiple installed versions.@uxf/* package that directly declares the dep). A conflict is reported only when these declarers land on different versions — transitive-only duplicates from unrelated third-party packages are filtered out.@uxf/* packages in your dependencies / devDependencies.peerDependencies from node_modules.@uxf/*, react, react-dom, and next (you manage these yourself).devDependencies are installed with -D.--fix, auto-installs missing peer deps using the detected package manager.Prints a JSON report of the current environment to stdout: Node, Yarn, Next, React, and react-dom versions plus the resolved version of every installed @uxf/* package (duplicates are flagged with isError: true). Supports Yarn 1 and Yarn 4, auto-detected from yarn -v. Run it inside the target project. No options.
npx uxf-audit
Downloads content from a URL and writes it under a # Global guidelines heading in the target file (default CLAUDE.md). If the heading exists, the content below it is replaced; otherwise the section is appended (or a new file is created).
Usage:
uxf-claude-sync [options]
Options:
--url Global guidelines URL [string]
--fileName Target file name (default: CLAUDE.md) [string]
-h, --help Show helpWalks a Next.js pages directory, follows each page's import graph (including @uxf/* packages and tsconfig path aliases), collects the translation namespaces referenced by t(...) calls and <Trans> components, and writes a route → namespaces map to a JSON file.
Usage:
uxf-i18n-namespaces-gen [options]
Options:
-i, --include Path prefixes to limit traversal to [array] [default: []]
-o, --output Output file [default: "i18n-pages.json"]
-n, --defaultNamespace Namespaces applied to every page [array] [default: ["common"]]
-p, --pagesDirectory Pages directory [default: "src/pages"]
-h, --help Show helpNamespaces found on /_app are merged into the global * entry.
Crawls a sitemap and requests every URL, reporting HTTP errors, duplicate sitemap entries, and (optionally) indexable pages missing from the sitemap. Can also follow nested page links and images. Sends a summary to Google Chat when errors are found and exits with code 1.
Usage:
uxf-sitemap-check [options]
Environment variables:
HTTP_USERNAME - optional
HTTP_PASSWORD - optional
Options:
--url Sitemap URL (required) [string]
-u, --http-username Basic-auth username (or HTTP_USERNAME) [string]
-p, --http-password Basic-auth password (or HTTP_PASSWORD) [string]
--skip Number of leading URLs to skip [number]
--with-nested Also test links found on each page [boolean]
--with-images Also test images found on each page [boolean]
--check-missing Report indexable pages missing from the
sitemap (requires --with-nested) [boolean]
--google-chat-webhook-url Where to send the results [string]
-h, --help Show help [boolean]Crawls a sitemap and writes a semicolon-separated export.csv (columns: url;title;og:title;description;og:description) into the working directory. The sitemap URL is taken from --url or the SITEMAP_URL environment variable.
Usage:
uxf-sitemap-meta-export [options]
Environment variables:
SITEMAP_URL - required (or use --url)
HTTP_USERNAME - optional
HTTP_PASSWORD - optional
SLACK_WEBHOOK_URL - optional
Options:
--url Sitemap URL (or use SITEMAP_URL) [string]
-u, --http-username Basic-auth username (or HTTP_USERNAME) [string]
-p, --http-password Basic-auth password (or HTTP_PASSWORD) [string]
-d, --dry-run Skip the Slack notification [boolean]
-h, --help Show help [boolean]main references a index.js that is not shipped; use the bin commands.uxf-release, uxf-push-notifier, and uxf-sitemap-meta-export expect GitLab CI / environment variables and mostly make sense inside a pipeline.uxf-sitemap-check --check-missing only works together with --with-nested; used alone it exits with code 1.uxf-merge-requests-notifier exists in the source tree but is not exposed as a bin command; it is run internally via the package's run:mr-notifier npm script and is not installed for consumers.