Development Guide

This guide is for developers working on the phenopackets-js library itself or those who need a deeper understanding of its setup.

Prerequisites

Before you begin development, ensure you have:

  • Node.js (LTS versions recommended)
  • npm or yarn
  • Protocol Buffer Compiler (protoc)
  • Git

Repository Setup

  1. Clone the repository:
git clone https://github.com/berntpopp/phenopackets-js.git
cd phenopackets-js
  1. Install dependencies:
npm install
  1. Download proto files:
# On Windows
scripts\download-protos.bat

# On Linux/macOS
bash ./scripts/download-protos.sh

Building the Library

After making changes or updating proto files:

  1. Generate JavaScript code from protos:
npm run generate-protos
  1. Run tests:
npm test

Code Style and Linting

The project uses ESLint and Prettier for code formatting:

  • Format code: npm run format
  • Check formatting: npm run format:check
  • Lint code: npm run lint
  • Fix lint issues: npm run lint:fix

Testing

Run the test suite:

npm test

Or in watch mode during development:

npm run test:watch

Documentation

Documentation Generation

The documentation is automatically generated and deployed using GitHub Actions when changes are pushed to the main branch. The process includes:

  • Building JSDoc API documentation from source code
  • Deploying to GitHub Pages
  • Updating the documentation site

For local development, you can generate the documentation using:

npm run docs:generate-api

Automated Workflows

The project uses GitHub Actions for automation:

  • Documentation: Automatically builds and deploys documentation on changes to main branch
  • Release: Uses semantic-release for automated versioning and publishing
  • CI: Runs tests and quality checks on pull requests

Workflow files are located in .github/workflows/:

  • docs.yml: Documentation generation and deployment
  • release.yml: Package versioning and publishing
  • ci.yml: Continuous integration checks

Release Process

The project uses semantic-release for versioning and publishing:

  1. Commits must follow the Conventional Commits specification
  2. CI/CD will automatically:
    • Run tests
    • Generate documentation
    • Create a release
    • Publish to npm

Project Structure 

phenopackets-js/
├── lib/              # Generated JavaScript code
├── protos/           # Protocol Buffer definitions (downloaded)
├── scripts/          # Build and utility scripts
├── src/              # Source code
├── tests/            # Test files
└── docs/             # Documentation

For more detailed information about specific aspects of development, see: