Skip to main content
Thank you for your interest in contributing to VK-IO! This guide will help you get started with contributing to the library.

​
Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub Issues

Suggest Features

Have an idea? Open a feature request

Improve Docs

Help make documentation clearer and more comprehensive

Submit Code

Fix bugs or implement new features

​
Getting Started

​
Prerequisites

VK-IO requires Node.js 12.20.0 or higher
Before contributing, make sure you have:
  • Node.js 12.20.0 or higher installed
  • npm, yarn, or pnpm package manager
  • Git installed and configured
  • A GitHub account

​
Development Setup

1

Fork the repository

Navigate to negezor/vk-io and click the Fork button
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/vk-io.git
cd vk-io
3

Install dependencies

npm ci --ignore-scripts
4

Build the project

npm run build
5

Run tests

npm test
Some tests require a VK API token. Set the TOKEN environment variable:
TOKEN=your_vk_token npm test

​
Project Structure

VK-IO is organized as a monorepo with multiple packages: 
vk-io/
├── packages/
│   ├── vk-io/              # Core library
│   ├── authorization/       # @vk-io/authorization
│   ├── session/            # @vk-io/session
│   ├── scenes/             # @vk-io/scenes
│   ├── streaming/          # @vk-io/streaming
│   ├── hear/               # @vk-io/hear
│   └── stateless-prompt/   # @vk-io/stateless-prompt
├── docs/                   # Documentation
└── scripts/                # Build scripts
Each package in packages/ has its own:
  • src/ - TypeScript source code
  • test/ - Test files
  • lib/ - Compiled output (generated)
  • package.json - Package configuration

​
Development Workflow

​
Making Changes

1

Create a branch

git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/ for new features
  • fix/ for bug fixes
  • docs/ for documentation changes
2

Make your changes

Edit the source files in the appropriate package’s src/ directory
3

Build and test

# Build all packages
npm run build

# Run tests
npm test

# Run linter
npm run check
4

Watch mode (optional)

For active development, use watch mode:
npm run watch

​
Code Style

VK-IO uses Biome for linting and formatting: 
# Check code style
npm run check

# Format code
npm run fmt

# Fix issues automatically
npm run fix
All code must pass linting checks before being merged. The CI will automatically verify this.

​
Writing Tests

Tests are written using Node.js built-in test runner: 
import { describe, it } from 'node:test';
import assert from 'node:assert';

describe('MyFeature', () => {
    it('should work correctly', () => {
        // Your test code
        assert.strictEqual(1 + 1, 2);
    });
});
Place test files in the test/ directory of the relevant package with a .test.ts extension.

​
Submitting Changes

​
Commit Guidelines

Write clear, descriptive commit messages: 
# Good commit messages
git commit -m "fix: resolve issue with message context forwarding"
git commit -m "feat: add support for mini apps attachments"
git commit -m "docs: improve upload examples"

# Less helpful commit messages (avoid)
git commit -m "fix bug"
git commit -m "update code"
git commit -m "changes"

​
Creating a Pull Request

1

Push your branch

git push origin feature/your-feature-name
2

Open a pull request

Go to the VK-IO repository and click New Pull Request
3

Fill in the details

Provide:
  • Clear title describing the change
  • Description explaining what and why
  • Related issues if applicable (e.g., “Fixes #123”)
  • Breaking changes if any
4

Wait for review

A maintainer will review your PR and may request changes

​
Pull Request Checklist

Before submitting, ensure your PR:
  • ✅ Passes all tests (npm test)
  • ✅ Passes linting (npm run check)
  • ✅ Includes tests for new features
  • ✅ Updates documentation if needed
  • ✅ Has a clear description

​
Continuous Integration

VK-IO uses GitHub Actions for CI/CD. Every pull request is automatically tested against multiple Node.js versions:
  • Node.js 18.x
  • Node.js 20.x
  • Node.js 22.x
The CI pipeline runs:
  1. Install dependencies
  2. Build all packages
  3. Run all tests
Your PR must pass all CI checks before it can be merged.

​
Reporting Issues

When reporting issues, please use the appropriate issue template:
Include:
  • What you did - Steps to reproduce
  • What you expected - Expected behavior
  • What happened - Actual behavior
  • Environment - vk-io version, Node.js version, OS
Report a bug
Include:
  • Use case - What problem does this solve?
  • Proposed solution - How should it work?
  • Alternatives - Other approaches you considered
Request a feature
When reporting issues for specific packages, use the appropriate label:
  • package: vk-io - Core library
  • package: authorization - @vk-io/authorization
  • package: session - @vk-io/session
  • package: scenes - @vk-io/scenes
  • package: streaming - @vk-io/streaming

​
Community Guidelines

Be Respectful

Treat everyone with respect and kindness

Be Constructive

Provide helpful feedback and suggestions

Be Patient

Maintainers are volunteers with limited time

Be Collaborative

Work together to improve the project

​
Getting Help

Need help contributing?

GitHub Discussions

Ask questions and discuss ideas

GitHub Issues

Search existing issues or create a new one

​
Additional Resources

VK API Documentation

Official VK API reference

VK API Schema

Auto-generated API schema

Community Modules

Explore ecosystem packages

Examples

Learn from example code

​
Thank You!

Your contributions make VK-IO better for everyone. Whether you’re fixing a typo in the docs or implementing a major feature, every contribution is valued and appreciated. Happy coding! 🚀

Build docs developers (and LLMs) love

Get started for freeTalk to us