Development Workflow

Purpose

This guide describes the common development workflow for working inside the Nrgy.js monorepo.

Repository Layout

• packages/*: publishable packages.
• docs/*: project, package, and developer-facing documentation.
• benchmarks/*: local benchmark scenarios.

Common Commands

npm install

npm run format

npm run check

npm run test

npm run build

Expected Flow for Source Changes

1. Update the source file and colocated tests.
2. Update colocated documentation for the changed module.
3. Update the package README.md if the public API or usage story changed.
4. Run npm run check.
5. Run npm run test for behavioral changes.

Documentation Workflow

• Source module docs live next to source files.
• Package overviews live in package-level README.md files.
• Russian translations use the .ru.md suffix.
• index.ts files must be documented through package README files rather than standalone index.md pages.

Documentation Website Workflow

• The source of truth for product and contributor docs is the repository docs/* tree, not website/docs/content/*.
• The website content under website/docs/content/* and website/docs/ru/content/* is generated by website/scripts/generate-content.mjs.
• When editing documentation, update the source files in docs/* first and keep the matching *.ru.md files in sync.

Website Commands

Run commands from website/package.json:

cd website
npm run dev

cd website
npm run build

• dev regenerates website/docs/content/* and starts the local VitePress server.
• build regenerates content and verifies that the site builds successfully.

When Website Config Must Be Updated

• If the documentation structure changes, update the sidebar and navigation in website/docs/.vitepress/config.ts.
• If docs move between sections, verify that generated routes under website/docs/content/docs/* still match the configured links.
• If public assets are added for the site, place them in docs/assets/* or website/docs/public/* depending on whether they should be copied by the content generator.

Release-Relevant Files

• Root CHANGELOG.md records project-level changes.
• Package CHANGELOG.md files track package-level releases.
• Package names and install commands must come from current package.json files.

Release Workflow

The release process is driven from the repository root through the scripts in package.json and the versioning rules in lerna.json.

Release Preparation

1. Make sure the working tree contains the intended changes only.
2. Run npm run check.
3. Run npm run test.
4. Run npm run build.
5. Verify that the relevant docs and changelog entries are up to date.

Versioning

Use the dry run first:

npm run preview:new-version

Create versions only after the dry run looks correct:

npm run new-version

• preview:new-version runs lerna version --dry-run.
• new-version runs lerna version with conventional commits enabled.
• Before versioning, the preversion hook runs npm run check, npm run build, and npm run test, then stages all changes with git add --all.

Publishing

After the packages are versioned and the release commit is ready, publish from the already versioned packages:

npm run new-publish

• new-publish runs lerna publish from-package.
• Package releases are based on the versions already written into the package manifests.

Release Notes and Validation

• Review the root CHANGELOG.md and the package CHANGELOG.md files after versioning.
• Confirm that generated docs and package READMEs still match the released API.
• If the website docs changed, run the site build from website/package.json before publishing.