Asset Build Workflow

This document explains the improved asset build workflow that prevents production deployments from overwriting local development builds.

Problem Solved

Previously, when running bin/deploy, the script would:

  1. Clean public/javascripts/webpack/* (wiping out local dev builds)
  2. Build production assets in the same directory
  3. Deploy to staging/production

This meant that after any deployment, your local development webpack build was gone and you'd need to rebuild it.

New Workflow

Development Assets

  • Command: yarn build
  • Output: public/javascripts/webpack/
  • Purpose: Local development builds that persist between deployments
  • When to use: When working on frontend changes locally

Production Assets (Deployment)

  • Command: bin/deploy
  • Output: public/javascripts/webpack-prod/<REV>/
  • Purpose: Production-optimized builds for deployment
  • When to use: When deploying to staging or production

Rollbar Source Maps

  • Production builds generate JS source maps and upload them to Rollbar.
  • The deploy pipeline and local Cap task set SEND_MAPS=true so the Rollbar plugin publishes maps with the current git revision.
  • To build manually with maps: NODE_ENV=production SEND_MAPS=true SHOW_MAPS=false yarn build.

Directory Structure

Local Development

public/javascripts/
├── webpack/                    # Development builds (persistent, committed)
│   ├── assets-manifest.json
│   └── *.bundle.js
└── webpack-prod/              # Production builds (temporary, gitignored)
    └── <REV>/                 # Git revision-specific assets
        ├── assets-manifest.json
        └── *.bundle.js

Server (After Deployment)

shared/public/javascripts/webpack/
└── <REV>/                     # Deployed production assets
    ├── assets-manifest.json
    └── *.bundle.js

Commands

Development

# Build development assets (standard workflow)
yarn build

# Watch mode for development
yarn build --watch

Production Deployment

# Deploy to staging
bin/deploy
# Select option 2 (Staging)

# Deploy to production  
bin/deploy
# Select option 1 (Production)

Webpack Dev Server (Hot Reload)

# For www subdomain
yarn wpd:www

# For crm subdomain
yarn wpd:crm

Benefits

  1. No More Lost Dev Builds: Local development assets persist between deployments
  2. Faster Development: No need to rebuild after every deployment
  3. Clean Separation: Development and production builds are completely isolated
  4. Standard Workflow: Uses normal yarn build for development
  5. Easy Cleanup: Production build directory can be safely deleted after deployment

Technical Details

  • The bin/deploy script uses WEBPACK_OUTPUT_DIR=public/javascripts/webpack-prod for production builds
  • Webpack configuration supports custom output directories via process.env.WEBPACK_OUTPUT_DIR
  • Capistrano asset upload task uploads from webpack-prod/ to server's webpack/ directory
  • Development builds use the standard public/javascripts/webpack/ directory
  • Production build directory (webpack-prod/) is gitignored to avoid committing large build artifacts

Troubleshooting

Development assets not loading?

# Rebuild development assets
yarn build

Production deployment failing?

# Check if production build directory exists
ls -la public/javascripts/webpack-prod/

# Clean and retry
rm -rf public/javascripts/webpack-prod/
bin/deploy

Want to clean up production build directory?

# Safe to delete after deployment
rm -rf public/javascripts/webpack-prod/