grunt-epublishing

Modern front-end build tools for ePublishing Jade and client sites.
Note: Grunt has been removed. Use npx epublishing-build or npm scripts.

Requirements

• Node.js >= 18.0.0
• Bundler and the jade gem (or jade client gem) in your Gemfile

Getting Started

1. Add the package

Add @epublishing/grunt-epublishing as a dev dependency:

npm install --save-dev @epublishing/grunt-epublishing

2. Add npm scripts to package.json

{
  "name": "my-site",
  "version": "1.0.0",
  "scripts": {
    "build": "epublishing-build",
    "build:watch": "epublishing-build --watch"
  },
  "devDependencies": {
    "@epublishing/grunt-epublishing": "^1.0.0"
  }
}

3. Run the build

# Full build (webpack + sass + concat/minify)
npm run build

# Watch mode (rebuilds on file changes)
npm run build:watch

Using npx (without installing)

npx epublishing-build              # Full build
npx epublishing-build --watch      # Watch mode

CLI Usage

epublishing-build [task] [options]

Tasks

| Task | Description | |------|-------------| | all (default) | Full build: webpack, sass, concat/minify | | webpack | Compile JS bundles only | | sass | Compile SCSS to CSS only | | concat | Concatenate and minify standalone JS only | | clean | Remove compiled assets | | tsconfig | Generate tsconfig.json files for IDEs | | clean-tsconfig | Remove generated tsconfig files |

Options

| Option | Description | |--------|-------------| | -w, --watch | Watch mode; rebuild on file changes | | --no-minify | Skip minification | | --analyze | Generate webpack bundle analysis | | --lint | Run ESLint | | -v, --verbose | Verbose output | | --parallel | Run webpack, sass, and concat in parallel | | --no-banner | Hide the build tools banner | | --env <env> | Set NODE_ENV | | --gc-between-tasks | Force GC between tasks (requires --expose-gc) |

Examples

# Full build
epublishing-build
npm run build

# Watch mode
epublishing-build --watch
npm run build:watch

# Webpack only
epublishing-build webpack

# Sass only
epublishing-build sass

# Webpack in watch mode
epublishing-build webpack --watch

# Production build with bundle analysis
epublishing-build --analyze --env production

Configuration

The build tools load configuration from the jade hierarchy: jade → jade child gem → site, merging in that order.

Configuration files are discovered in this order:

1. config/build.config.js (new)
2. config/grunt-config.js (legacy, still supported)

Config can export a function that receives the base config:

// config/build.config.js or config/grunt-config.js
module.exports = function(baseConfig) {
  return {
    webpack: {
      dist: {
        entry: { ... },
        output: { ... }
      }
    },
    sass: { ... },
    concat: { ... }
  };
};

Or a plain object:

module.exports = {
  webpack: { ... },
  sass: { ... }
};

What the build does

1. Resolve paths: Finds jade gem, jade child gem (if any), and site directories via Bundler
2. npm install: Runs npm ci (or npm install) in jade and jade child gem directories that have package.json. Installs dependencies from each gem—the site's npm install remains manual.
3. Webpack: Compiles JS modules from app/js with SWC, outputs to public/javascripts/app/bundle
4. Sass: Compiles SCSS to CSS using sass-embedded
5. Concat/Minify: Concatenates and minifies standalone scripts into jade.default.js and similar outputs

Local Development

To develop or debug the build tools against a Jade site:

# Inside the grunt-epublishing directory:
npm link

# In your site directory:
npm link @epublishing/grunt-epublishing

Then run epublishing-build from the site; it will use your local clone.

Migration from Grunt

If you were using the old Grunt-based setup:

Before (Grunt):

// Gruntfile.js
module.exports = function(grunt) {
  grunt.loadNpmTasks('@epublishing/grunt-epublishing');
  grunt.registerTask('default', ['jade']);
};

grunt
grunt jade

After:

• Remove the Gruntfile (or repurpose it if you have custom tasks)
• Add npm scripts: "build": "epublishing-build", "build:watch": "epublishing-build --watch"
• Run npm run build or npx epublishing-build instead of grunt

Existing config/grunt-config.js files continue to work; no config changes required.

Release Management

If using bumped (see .bumpedrc), version bumping and publishing can be automated. Otherwise, manually bump version in package.json, commit, tag, and run npm publish.