FreshJuice DEV uses semantic versioning with automated scripts to keep version numbers synchronized across package.json and theme.json. This guide explains the version management system.
Semantic Versioning FreshJuice DEV follows SemVer (Semantic Versioning) with the format:
MAJOR : Breaking changes or major feature releasesMINOR : New features, backward-compatiblePATCH : Bug fixes and minor updates
Version Bump Scripts FreshJuice DEV includes automated version management scripts that:
Bump version in package.json
Sync version to theme/theme.json
Maintain consistency across the project
Available Commands # Bump patch version (3.0.0 → 3.0.1) npm run version:patch # Bump minor version (3.0.0 → 3.1.0) npm run version:minor # Bump major version (3.0.0 → 4.0.0) npm run version:major
Bumping Versions
Choose the appropriate version bump
Decide which version component to increment: Patch (3.0.0 → 3.0.1):
Bug fixes
Minor style tweaks
Documentation updates
Minor (3.0.0 → 3.1.0):
New features
New modules or templates
Backward-compatible enhancements
Major (3.0.0 → 4.0.0):
Breaking changes
Major redesign
Incompatible API changes
Run the version bump command
Execute the appropriate script: This runs ./scripts/bump-theme-version.sh patch
Verify the version update
The script will output: Bumping version... Bumping version with "patch" mode. Please wait... Current version: 3.0.0 New version: 3.0.1 Version bumped successfully!
Commit the changes
The script modifies two files:
package.jsontheme/theme.json Commit these changes: git add package.json theme/theme.json git commit -m "Bump version to 3.0.1"
How the Version Script Works The bump-theme-version.sh script automates the version bump process:
Script Breakdown
Prerequisites check
The script requires jq (JSON processor): if ! [ -x "$( command -v jq)" ]; then echo "Error: jq is not installed." >&2 exit 1 fi
Install jq if needed: # macOS brew install jq # Ubuntu/Debian sudo apt-get install jq # Windows (via Chocolatey) choco install jq
Validate bump mode
Accepts only valid modes: mode = ${1 :- patch } if [ " $mode " != "major" ] && [ " $mode " != "minor" ] && [ " $mode " != "patch" ]; then echo "Invalid mode. Please use major, minor or patch." exit 1 fi
Bump package.json version
Uses npm’s built-in version command: CURRENT_VERSION = $( node -p "require('./package.json').version" ) npm version " $mode " --no-git-tag-version NEW_VERSION = $( node -p "require('./package.json').version" )
The --no-git-tag-version flag prevents automatic git tagging.
Sync to theme.json
Updates the theme configuration: jq ".version = \" $NEW_VERSION \" " theme/theme.json > theme/theme.json.tmp mv theme/theme.json.tmp theme/theme.json
This ensures HubSpot recognizes the new version. Version Management Workflow Complete Release Process
Make your changes
Develop features, fix bugs, or update documentation.
Build the theme
Create production build: This creates a ZIP file with the new version number: ./_dist/freshjuice-dev-hubspot-theme-v3.1.0-dev.zip
Commit version changes
Commit the version bump: git add package.json theme/theme.json git commit -m "Bump version to 3.1.0"
Create a git tag
Tag the release: git tag v3.1.0 git push origin main --tags
Version Consistency Files Managed by Scripts The version management system keeps these files synchronized:
package.json :{ "name" : "freshjuice-dev-hubspot-theme" , "version" : "3.0.0" , ... }
theme/theme.json :{ "label" : "FreshJuice DEV" , "version" : "3.0.0" , ... }
Distribution ZIP filename :freshjuice-dev-hubspot-theme-v3.0.0-dev.zip
Manual Version Updates Avoid manually editing version numbers in package.json or theme.json. Always use the version bump scripts to ensure synchronization.
If you must manually update versions:
Update package.json
Update theme/theme.json
Verify both files have the same version number
Run npm run build to verify the ZIP filename is correct
Best Practices
Bump before building for release
Never bump during active development
Bump after merging feature branches
Create a git tag after version bumps
Patch : Small fixes, no new featuresMinor : New features, maintains compatibilityMajor : Breaking changes, major updatesFollow conventional commits for clarity
# Feature development git checkout -b feature/new-module # ... make changes ... git commit -m "Add new hero module" # Merge to main git checkout main git merge feature/new-module # Bump version and release npm run version:minor npm run build git add package.json theme/theme.json git commit -m "Bump version to 3.1.0" git tag v3.1.0 git push origin main --tags
For urgent bug fixes: # Create hotfix branch git checkout -b hotfix/critical-bug # Fix the bug git commit -m "Fix critical navigation bug" # Bump patch version npm run version:patch # Build and deploy immediately npm run build npm run upload:hubspot # Merge back to main git checkout main git merge hotfix/critical-bug git push origin main --tags
Troubleshooting Script fails with “jq is not installed”:
Install jq using your package manager (see script breakdown above)
Verify installation: jq --version
Version numbers out of sync:
Run the version script again to resynchronize
Check both package.json and theme/theme.json
Manually fix if necessary, then run npm run build
Git conflicts on version bump:
Resolve conflicts in package.json and theme/theme.json
Run version script again after resolving
Ensure only one version bump happens per release
ZIP file has wrong version:
Verify package.json version is correct
Run npm run build again to regenerate ZIP
Check ./_dist/ directory for the updated file
Next Steps
Building the Theme Build production-ready packages with version numbers
HubSpot CLI Guide Deploy versioned themes to HubSpot
