Local Development Guide¶

This guide explains how to develop and test changes to @verdikta/common locally before publishing to npm.

Overview¶

When making changes to @verdikta/common, you often want to test those changes in other projects (like verdikta-arbiter) before publishing a new version. This document covers the workflow for local development and integration testing.

Prerequisites¶

• Node.js and npm installed
• Access to both verdikta-common and the consuming project repositories
• Understanding of relative file paths between projects

Local Development Workflow¶

1. Making Changes to verdikta-common¶

1. Navigate to verdikta-common directory:

   cd /path/to/verdikta-common
   

2. Make your changes to source files (src/, docs/, etc.)

3. Run tests locally:

   npm test
   

4. Run linting:

   npm run lint
   

2. Installing Local Version in Consuming Projects¶

There are several methods to use your local verdikta-common in other projects:

Method 1: Automated Script (Recommended)¶

Use the provided installation script for easy setup:

# In verdikta-common directory
cd /path/to/verdikta-common

# Install in a specific project
./scripts/install-local.sh ../verdikta-arbiter/external-adapter

# Install in all known Verdikta projects
./scripts/install-local.sh --all

# Install and run tests
./scripts/install-local.sh ../project --test

# Interactive mode (will prompt for project path)
./scripts/install-local.sh

Method 2: Manual File Installation¶

This method creates a direct link to your local development version.

# In the consuming project directory (e.g., verdikta-arbiter/external-adapter)
cd /path/to/consuming-project

# Remove existing verdikta-common
npm uninstall @verdikta/common

# Install local version using relative path
npm install file:../../verdikta-common

# Or absolute path
npm install file:/absolute/path/to/verdikta-common

Example for verdikta-arbiter:

cd /root/verdikta-arbiter/external-adapter
npm uninstall @verdikta/common
npm install file:../../verdikta-common

Method 3: npm link (Alternative)¶

# In verdikta-common directory
cd /path/to/verdikta-common
npm link

# In consuming project directory
cd /path/to/consuming-project
npm link @verdikta/common

Note: npm link can sometimes have issues with peer dependencies and different Node.js versions. File installation is generally more reliable.

Method 4: Pack and Install (For testing packaging)¶

# In verdikta-common directory
npm pack
# This creates verdikta-common-1.0.2-beta.1.tgz

# In consuming project directory
npm install /path/to/verdikta-common-1.0.2-beta.1.tgz

3. Verifying Local Installation¶

After installation, verify the local version is being used:

# Check package.json dependencies
cat package.json | grep "@verdikta/common"

# Check node_modules installation
ls -la node_modules/@verdikta/common

# Check which version is resolved
npm list @verdikta/common

You should see something like:

@verdikta/common@file:../../verdikta-common

4. Testing Changes¶

1. Run the consuming project's tests:

   npm test
   

2. Test specific functionality that uses your changes

3. Verify integration works as expected

Development Tips¶

Hot Reloading Changes¶

When using file installation, changes to verdikta-common source files are immediately available in the consuming project. However:

• JavaScript changes: Restart the consuming application
• Configuration changes: May require reinstalling
• Package.json changes: Require reinstalling

Testing Multiple Projects¶

If you have multiple projects that use @verdikta/common:

# Script to update all consuming projects
#!/bin/bash
VERDIKTA_COMMON_PATH="/path/to/verdikta-common"

# List of consuming projects
PROJECTS=(
  "/path/to/verdikta-arbiter/external-adapter"
  "/path/to/another-project"
)

for project in "${PROJECTS[@]}"; do
  echo "Updating $project..."
  cd "$project"
  npm uninstall @verdikta/common
  npm install "file:$VERDIKTA_COMMON_PATH"
done

Version Management¶

To avoid confusion, consider updating the version in package.json with development tags:

{
  "version": "1.0.2-dev.1",
  "version": "1.0.2-feature-xyz",
  "version": "1.0.2-bugfix-validation"
}

Switching Back to Published Version¶

When you're ready to use the published version again:

# In consuming project directory
npm uninstall @verdikta/common
npm install @verdikta/common@latest

# Or install specific version
npm install @verdikta/common@1.0.1

Publishing Workflow¶

Once local testing is complete:

1. Beta Release (Recommended)¶

# In verdikta-common directory
# Update version for beta
npm version 1.0.2-beta.1

# Run full test suite
npm run build  # This runs lint and tests

# Publish beta version (requires npm login)
npm publish --tag beta

2. Test Beta in Consuming Projects¶

# In consuming projects
npm uninstall @verdikta/common
npm install @verdikta/common@beta

3. Stable Release¶

# In verdikta-common directory
npm version 1.0.2
npm publish

Troubleshooting¶

Common Issues¶

1. Module Not Found Errors: - Ensure the file path is correct - Check that all dependencies are installed in verdikta-common - Try removing node_modules and package-lock.json, then reinstalling

2. Version Conflicts: - Clear npm cache: npm cache clean --force - Delete node_modules and reinstall - Check for conflicting peer dependencies

3. Changes Not Reflected: - Restart the consuming application - Verify you're editing the correct files - Check if changes require a full reinstall

4. Path Issues: - Use absolute paths if relative paths don't work - Ensure verdikta-common has been built if required

Debugging Local Installation¶

# Check what's actually installed
npm ls @verdikta/common

# Check file contents
cat node_modules/@verdikta/common/package.json

# Verify source files
ls -la node_modules/@verdikta/common/src/

Best Practices¶

1. Always run tests in both verdikta-common and consuming projects
2. Use descriptive development versions (e.g., 1.0.2-fix-validation)
3. Document breaking changes clearly
4. Test with beta versions before stable releases
5. Keep local development branches separate from main
6. Use consistent Node.js versions across projects

Example Complete Workflow¶

Here's a complete example of testing a validator fix:

# 1. Make changes to verdikta-common
cd /root/verdikta-common
# Edit src/utils/validator.js
npm test  # Verify tests pass

# 2. Update version for development
npm version 1.0.2-dev.validator-fix

# 3. Install in external adapter
cd /root/verdikta-arbiter/external-adapter
npm uninstall @verdikta/common
npm install file:../../verdikta-common

# 4. Test the integration
npm test
# Test specific functionality

# 5. If tests pass, publish beta
cd /root/verdikta-common
npm version 1.0.2-beta.1
npm publish --tag beta

# 6. Test beta in production-like environment
cd /root/verdikta-arbiter/external-adapter
npm uninstall @verdikta/common
npm install @verdikta/common@beta

# 7. If beta tests pass, publish stable
cd /root/verdikta-common
npm version 1.0.2
npm publish

This workflow ensures thorough testing before any public releases while maintaining development velocity.