TypeScript SDK

This guide will help you get started with contributing to the Opik TypeScript SDK.

Project Structure

The TypeScript SDK is located in the sdks/typescript directory. Here's an overview of the key files and directories:

src/: Contains the main source code
tests/: Contains test files
examples/: Contains example usage of the SDK
package.json: Project dependencies and scripts
tsconfig.json: TypeScript configuration
tsup.config.ts: Build configuration
vitest.config.ts: Test configuration

Setup

Set up Opik Locally
To develop and test TypeScript SDK features, you'll need a local Opik instance running:
- Linux/Mac
Bash
# From the root of the repository ./opik.sh --port-mapping

powershell

# From the root of the repository
.\opik.ps1 --port-mapping

:::

Note: The --port-mapping flag exposes all service ports (including MySQL on 3306, ClickHouse on 8123, Redis on 6379) which is useful for debugging. The TypeScript SDK routes traffic through the API gateway (nginx) in the frontend service.

Your local Opik server will be accessible at http://localhost:5173. :::

Install dependencies

bash cd sdks/typescript npm install

Build the SDK

bash npm run build

Run tests

bash npm test

:::

Development Workflow

Create a new branch
Create a new branch for your changes

Make your changes

Implement your changes

Add tests

Add tests for new functionality

Run test suite

Run the test suite to ensure everything works

Build the SDK

Build the SDK to ensure it compiles correctly

Submit PR

Submit a pull request

:::

Testing

We use Vitest for testing. Tests are located in the tests/ directory. When adding new features:

Write unit tests
Write unit tests for your changes

Run tests

Ensure all tests pass with npm test

Check coverage

Maintain or improve test coverage

:::

Building

The SDK is built using tsup. To build:

Bash

npm run build

This will create the distribution files in the dist/ directory.

Documentation

When adding new features or making changes:

Update README
Update the README.md if necessary

Add JSDoc

Add JSDoc comments for new functions and classes

Add examples

Include examples in the examples/ directory

Update docs

Update the main documentation if necessary. See the Documentation Guide for details.

:::

Code Style

We use ESLint for code style enforcement. The configuration is in eslint.config.js. Before submitting a PR:

Run linter
Run npm run lint to check for style issues

Fix issues

Fix any linting errors

Check style

Ensure your code follows the project's style guidelines

:::

Pull Request Process

Fork repository
Fork the repository

Create branch

Create your feature branch

Make changes

Make your changes

Run checks

Run tests and linting

Submit PR

Submit a pull request

:::

Your PR should:

Have a clear description of the changes
Include tests for new functionality
Pass all CI checks
Follow the project's coding standards

Need Help?

If you need help or have questions:

Open an issue on GitHub
Join our Comet Chat community
Check the existing documentation

Remember to review our Contributor License Agreement (CLA) before contributing.