Skip to main content

​
Installation Guide

This guide provides detailed instructions for installing FreshJuice DEV and setting up your development environment.

​
Prerequisites

Before installing FreshJuice DEV, ensure you have the following installed and configured:

​
Required Software

1

Node.js (v22.0.0 or newer)

FreshJuice DEV requires Node.js version 22.0.0 or higher.Check your Node.js version:
node --version
Install or update Node.js:Download the latest version from nodejs.org or use a version manager:
# Using nvm (recommended)
nvm install 22
nvm use 22
We recommend using nvm (Node Version Manager) to manage Node.js versions.
2

HubSpot CMS CLI

The HubSpot CLI is required for local development and deployment.Install the HubSpot CLI globally:
npm install -g @hubspot/cli
Verify installation:
hs --version
See the HubSpot CLI documentation for more details.
3

HubSpot Account

You need access to a HubSpot account with CMS Hub permissions.
  • CMS Hub Starter or higher is required
  • Ensure you have Design Manager access
  • Have your Portal ID ready
4

Git (Optional but Recommended)

Git is needed to clone the repository and manage version control.Check if Git is installed:
git --version
Install Git:Download from git-scm.com or use your package manager:
# macOS (via Homebrew)
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows (via Chocolatey)
choco install git

​
Installation Steps

​
1. Clone the Repository

Clone the FreshJuice DEV repository to your local machine: 
git clone [email protected]:freshjuice-dev/freshjuice-dev-hubspot-theme.git
cd freshjuice-dev-hubspot-theme

​
2. Install Dependencies

Install all required npm packages: 
npm install
This will install:
  • Tailwind CSS v4 – For utility-first styling
  • Alpine.js v3 – For reactive components
  • esbuild – For fast JavaScript bundling
  • Development tools – Husky, npm-run-all, rimraf, and more
The installation process may take a few minutes depending on your internet connection.

​
3. Prepare Development Environment

Install Husky git hooks for code quality: 
npm run prepare
This sets up pre-commit hooks to ensure code consistency.

​
4. Authenticate with HubSpot

Connect the HubSpot CLI to your HubSpot account: 
hs auth
You’ll be prompted to:
  1. Choose OAuth or Personal Access Key authentication
  2. Enter your Portal ID (found in HubSpot settings)
  3. Complete authentication in your browser
Make sure you’re authenticating with a HubSpot account that has CMS Hub access and Design Manager permissions.

​
5. Configure Upload Destination (Optional)

By default, the theme uploads to /FreshJuiceDEV in your HubSpot portal. To change this:
  1. Open package.json
  2. Find the upload:hubspot and watch:hubspot scripts
  3. Change /FreshJuiceDEV to your preferred destination
"scripts": {
  "upload:hubspot": "hs upload ./theme /YourThemeName",
  "watch:hubspot": "hs watch ./theme /YourThemeName"
}

​
Verify Installation

Ensure everything is set up correctly:
1

Check Node.js and npm

node --version  # Should be v22.0.0 or higher
npm --version
2

Check HubSpot CLI

hs --version
hs accounts list  # Should show your authenticated account
3

Test build process

npm run build
This should:
  • Clean temporary directories
  • Bundle JavaScript files
  • Compile Tailwind CSS
  • Create a distribution ZIP
If the build completes without errors, your environment is properly configured.
4

Test upload to HubSpot

npm run upload:hubspot
This uploads the theme to your HubSpot portal. Check the Design Manager to confirm:
  1. Go to Marketing → Files → Design Tools
  2. Navigate to /FreshJuiceDEV (or your custom path)
  3. Verify theme files are present

​
Development Workflow

Once installed, you have several commands available:

​
Local Development

Start the development server with hot-reload: 
npm run start
This runs three processes in parallel:
  1. Tailwind CSS watcher – Rebuilds CSS on changes
  2. JavaScript bundler – Rebuilds JS on changes
  3. HubSpot file watcher – Auto-uploads to HubSpot
Leave this running while you develop. Changes will automatically sync to HubSpot.

​
Production Build

Build optimized files for production: 
npm run build
This creates:
  • Minified CSS in theme/css/tailwind.css
  • Bundled JavaScript in theme/js/main.js
  • Distribution ZIP in _dist/ directory

​
Manual Upload

Upload the theme without watching: 
npm run upload:hubspot

​
Individual Build Commands

You can also run build steps individually: 
# Build CSS once
npm run build:tailwind

# Watch CSS for changes
npm run watch:tailwind

​
Troubleshooting

​
Node.js Version Errors

Problem: Error: The engine "node" is incompatible with this module Solution: Upgrade to Node.js v22.0.0 or higher: 
nvm install 22
nvm use 22

​
HubSpot Authentication Issues

Problem: Error: Unauthorized or No valid authentication found Solution: Re-authenticate with HubSpot: 
hs auth
Make sure you select the correct portal when prompted.

​
Build Failures

Problem: npm run build fails with errors Solutions:
  1. Clear npm cache and reinstall: 
    rm -rf node_modules package-lock.json
npm install
  2. Check for syntax errors in source files: 
    npm run build:js  # Check JavaScript
npm run build:tailwind  # Check CSS
  3. Ensure all dependencies are installed: 
    npm install

​
Upload Errors

Problem: Files not uploading to HubSpot Solutions:
  1. Verify authentication: 
    hs accounts list
  2. Check portal permissions (need Design Manager access)
  3. Verify the upload path exists or create it manually in HubSpot
  4. Try uploading manually: 
    hs upload ./theme /FreshJuiceDEV --portal=YOUR_PORTAL_ID
If you continue experiencing issues, check the GitHub issues or open a new issue with details about your problem.

​
Next Steps

Now that FreshJuice DEV is installed, you’re ready to start developing:

Quick Start

Follow the quick start guide to create your first page.

Project Structure

Learn about the theme’s file organization.

Configuration

Customize theme settings and behavior.

Development Guide

Deep dive into theme development workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us