Contributing

Messagevisor is an open source monorepo. Packages live under packages/, example projects live under projects/, and documentation lives under docs/.

Repository layout#

packages/
├── types/                  # shared TypeScript types
├── core/                   # builder, evaluator, linter, tester, CLI plugins
├── cli/                    # messagevisor CLI entry point
├── sdk/                    # JavaScript/TypeScript runtime SDK
├── react/                  # React provider and hooks
├── react-intl-compat/      # react-intl compatibility layer
├── catalog/                # catalog UI and static generator
├── module-icu/             # ICU message format module
└── module-interpolation/   # interpolation module
projects/
├── project-yml/            # minimal YAML starter
├── project-json/           # minimal JSON starter
├── project-raw/            # YAML starter without the ICU module
├── project-environments/   # sets-based dev/staging/production starter
├── project-sets/           # sets-based starter
├── project-test-envs/      # sets with restricted promotion flows
├── project-demo/           # sets-based ecommerce demo for walkthroughs
├── project-rtl/            # RTL-aware locale showcase
└── project-1/              # broad internal example used for development
docs/                       # documentation source

Local setup#

Clone the repository and install dependencies from the root:

$ git clone https://github.com/messagevisor/messagevisor.git
$ cd messagevisor
$ make install

This runs npm install across all packages in the workspace.

Build all packages#

$ make build

Individual packages can be built directly:

$ npm run build --workspace packages/core
$ npm run build --workspace packages/sdk

You can also build a single package by cd-ing into it:

$ (cd packages/sdk && npm run build)

Run the test suite#

$ make test

To run tests for a single package:

$ npm test --workspace packages/core

Type-check#

$ make typecheck

This catches TypeScript errors in spec files and other sources that normal builds omit from tsc. Per-package: (cd packages/sdk && npm run typecheck).

Lint and format#

$ make lint
$ make format

lint runs ESLint and Prettier in check mode. format rewrites files in place.

Use an example project for manual testing#

The projects/ directory contains example Messagevisor projects you can run commands against:

$ cd projects/project-1
$ npx messagevisor lint
$ npx messagevisor build
$ npx messagevisor test
$ npx messagevisor catalog

After changing core behavior, run the relevant example project commands to verify that the output matches expectations.

Package changes#

If you modify package.json in any package, run npm install from the repository root to update the workspace lockfile:

$ npm install

Making a change#

1. Fork the repository and create a branch from main
2. Make your change
3. If you changed CLI behavior or a YAML schema, update the relevant doc in docs/
4. If you changed build output, verify behavior against an example project in projects/
5. Run make test and confirm everything passes
6. Open a pull request

Docs contributions#

Documentation source files are in docs/. Each page is a Markdown file named page.md inside a directory matching the URL path.

If you are adding a new feature, add or update the corresponding doc. If you are fixing a bug, check whether the existing doc is misleading or incorrect and update it at the same time.

Style notes:

• Lead paragraph uses {% .lead %} markup
• Code blocks use language tags and {% path="..." %} for file path annotations
• Keep examples short and concrete
• End each page with a ## Related section linking to related pages where relevant

Useful habits#

• Keep examples in projects/ aligned with current behavior. Out-of-date examples mislead contributors.
• Run make build before testing against an example project so the local packages are fresh.
• Touch only the packages that are relevant to your change. Avoid broad reformatting that makes diffs harder to review.
• Write a clear commit message that describes what changed and why, not just what the files contain.