# Contributing
How the dotlottie-js project is set up, built, and tested, and how to contribute or report issues.

# Contributing to dotlottie-js

This page is for developers interested in the `dotlottie-js` project setup, build process, or contributing — not for consumers of the published `@dotlottie/dotlottie-js` package.

## Source Code Repository

The source code for `dotlottie-js` is hosted on GitHub:

- **Repository URL:** [https://github.com/dotlottie/dotlottie-js](https://github.com/dotlottie/dotlottie-js)

Here you can find the latest code, report issues, and contribute.

## Project Structure

`dotlottie-js` is a pnpm workspace monorepo managed with [Turborepo](https://turbo.build/):

- `packages/dotlottie-js/`: The published `@dotlottie/dotlottie-js` package.
  - `src/v1/` and `src/v2/`: Format-specific implementations, each split into `browser/`, `node/`, and `common/` (shared logic) subfolders, plus a `common/schemas/` directory holding the `valibot` schemas that validate themes, state machines, and the manifest.
  - `src/index.browser.ts` / `src/index.node.ts`: The two entry points — the package's `exports` field routes to the Node build automatically when imported from a Node.js runtime.
- `apps/`: Supporting applications (docs generation, etc.).
- `pnpm-workspace.yaml` / `turbo.json`: Monorepo and task-runner configuration.

## Project Setup

The repository enforces `pnpm` as the package manager — a `preinstall` script (`npx only-allow pnpm`) blocks `npm install`/`yarn install`.

```bash
git clone https://github.com/dotlottie/dotlottie-js.git
cd dotlottie-js
pnpm install
```

## Build Process

Builds run through Turborepo, which fans out to each package's own build script:

```bash
pnpm build   # runs `turbo run build`
```

Within `packages/dotlottie-js`, the library itself is built with `tsup` and type-checked with `tsc`.

## Running Tests

Tests run separately for each target environment using Vitest — Node tests with `vitest.config.js`, and browser tests (via Playwright) with `vitest.browser.config.js`:

```bash
pnpm test          # runs `turbo run test` across the workspace
# or, from packages/dotlottie-js:
pnpm test:node
pnpm test:browser
```

## Contribution Guidelines

Generally, the process for contributing involves:

1. Fork the repository.
2. Create a feature or bugfix branch.
3. Make your changes, including tests.
4. Ensure `pnpm lint` and `pnpm test` pass.
5. Add a changeset (`pnpm changelog`, backed by [Changesets](https://github.com/changesets/changesets)) describing your change, if it affects a published package.
6. Submit a pull request to the main repository, clearly describing your changes.

## Reporting Issues

Use the **Issues** tab on the GitHub repository to report bugs, request features, or ask questions:

- **Report an Issue:** [https://github.com/dotlottie/dotlottie-js/issues](https://github.com/dotlottie/dotlottie-js/issues)

When reporting bugs, please provide:

- A clear description of the issue.
- The `dotlottie-js` version.
- Environment (Browser/Node.js version, OS).
- Steps to reproduce the issue.
- Code samples, if applicable.
- Any relevant error messages.

## License

`dotlottie-js` is distributed under the **MIT License**.