React Native Vosk Speech Recognition

Expert guidance for developing the react-native-vosk offline speech recognition module. This skill helps you work with React Native native modules, Vosk API integration, and cross-platform mobile development.

Repository Overview

This is a React Native library providing offline speech recognition using the Vosk API. The project is structured as a Yarn workspaces monorepo containing:

Development Environment

Prerequisites

Initial Setup

1. Ensure Node.js v18+ is active: `nvm use`

2. Install dependencies: `yarn install --immutable`

3. Never use npm for package management - Yarn is enforced

Build & Test Workflow

Library Development

```bash

Install dependencies

yarn

Build the library

yarn prepare

Type checking

yarn typecheck

Linting (with auto-fix)

yarn lint

yarn lint --fix

Run tests

yarn test

Clean build artifacts

yarn clean

```

Example App Testing

```bash

Run on Android

yarn example android

Run on iOS

yarn example ios

```

Pre-commit Validation

The repository uses Lefthook for pre-commit hooks that automatically run:

Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/en) format.

Project Structure

Key Directories

- `src/index.tsx` - Main entry point

- `src/index.d.ts` - Type definitions

- `src/__tests__/` - Jest unit tests

- `android/src/main/java/com/vosk/VoskModule.kt` - Core module

- `android/src/main/java/com/vosk/VoskPackage.kt` - Package definition

- `ios/Vosk.swift` - Swift implementation

- `ios/Vosk.mm` - Objective-C++ bridge

- `ios/VoskModel.swift` - Model handling

- `ios/libvosk.xcframework/` - Vosk framework

- `example/src/App.tsx` - Demo application

- `example/android/` - Android example project

- `example/ios/` - iOS example project

Configuration Files

Vosk Model Setup

Downloading Models

Download Vosk models from [alphacephei.com/vosk/models](https://alphacephei.com/vosk/models)

Android Model Installation

Place models in: `example/android/app/src/main/assets/model-<lang>/`

iOS Model Installation

Add models to the Xcode project (see README for detailed steps)

Validation Checklist

Before submitting changes:

1. ✓ Run `yarn lint` - ensure no linting errors

2. ✓ Run `yarn typecheck` - verify TypeScript types

3. ✓ Run `yarn test` - all tests pass

4. ✓ For native changes: rebuild example app on both platforms

5. ✓ Verify commit message passes pre-commit hooks

6. ✓ Check CI status on pull requests

CI/CD Pipeline

GitHub Actions Workflows

Publishing

Releases are managed with `release-it`:

```bash

yarn release

```

(Requires appropriate permissions)

Troubleshooting

Build Issues

1. Run `yarn clean` to remove build artifacts

2. Run `yarn install` to reinstall dependencies

3. Retry the build

Native Code Not Updating

Model Loading Failures

Best Practices

1. **Always use Yarn** - npm is only for publishing

2. **Follow Conventional Commits** - required for automated releases

3. **Test both platforms** - verify Android and iOS functionality

4. **Run validation before committing** - lint, typecheck, and test

5. **Keep models updated** - check Vosk website for model updates

6. **Document native changes** - add comments for complex native code

Additional Resources