@epublishing/grunt-epublishing 1.0.7 → 1.1.2

package/README.md

@@ -1,113 +1,204 @@
 # grunt-epublishing
 
-> Automated front-end tasks for ePublishing Jade and client sites.
+> 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
-This plugin requires Grunt v1.0.0.
 
-If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins.
+### 1. Add the package
 
-NodeJS and Grunt-Cli must be installed before you proceed.
+Add `@epublishing/grunt-epublishing` as a dev dependency:
 
-If you are on Mac OS X and use homebrew. The following commands will get you ready to run grunt.
+```bash
+npm install --save-dev @epublishing/grunt-epublishing
+```
 
+### 2. Add npm scripts to `package.json`
 
-```sh
-brew install node
-npm install -g grunt-cli
+```json
+{
+  "name": "my-site",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "epublishing-build",
+    "build:watch": "epublishing-build --watch"
+  },
+  "devDependencies": {
+    "@epublishing/grunt-epublishing": "^1.0.0"
+  }
+}
 ```
 
-* To get started with using Grunt Jade you first need the right files within the project you wish to use this plugin. You will create a package.json and gruntfile.js in the root of your application. (unless someone has already done this)
+### 3. Run the build
 
-* The gruntfile should contain the following code which enables the default jade task:
+```bash
+# Full build (webpack + sass + concat/minify)
+npm run build
 
+# Watch mode (rebuilds on file changes)
+npm run build:watch
+```
 
-```js
-module.exports = function(grunt) {
-  // Load the grunt jade task
-  grunt.loadNpmTasks('@epublishing/grunt-epublishing');
+### Using npx (without installing)
 
-  // Run jade-default Grunt Task
-  grunt.registerTask('default', ['jade']);
-};
+```bash
+npx epublishing-build              # Full build
+npx epublishing-build --watch      # Watch mode
 ```
 
-* The package.json file will contain the name of your site, version, and required dependencies that get installed before you can run "grunt". This file would look similar to this, and includes the actual required dependencies for Grunt Jade:
+---
 
+## CLI Usage
 
-```json
-{
-  "name": "jade-labs",
-  "version": "0.1.0",
-  "description":"jade-labs",
-  "repository": {
-    "type": "git",
-    "url": "git@bitbucket.org:epub_dev/jade"
-  },
-  "devDependencies": {
-    "grunt": "^1.0.0",
-    "grunt-jade": "git+ssh://git@bitbucket.org:epub_dev/grunt-jade.git"
-  }
-}
+```bash
+epublishing-build [task] [options]
 ```
 
-* Install the npm modules that this Grunt task depends on. To do this, run the following command in the application you wish to use this plugin.
-
-```sh
-npm install
+### 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
+
+```bash
+# 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
 ```
 
-Awesome! You are ready to run Grunt in the command line and watch Grunt Jade start working on your front-end assets. Grunt Jade will concatenate and minify the SCSS and Javascript. Here is what `grunt-jade` does when you run `grunt`:
-
-1. `set-jade-paths`: Resolve the locations of the active Jade gem, Jade child gem (if there is one), and site directories, making them available as config variables to subsequent tasks.
-1. `npm-install`: Install Node module dependencies in Jade and child gem locations if `package.json` files are present.
-1. `clean`: Clean (delete) previously compiled assets, if any.
-1. `babel`: Transpile standalone ES2015 scripts into public/javascripts/app with Babel.
-1. `concat`: Concatenate our default JS assets into a single script, `jade.default.js`.
-1. `uglify`: Minify the above script.
-1. `webpack`: Compile configured modules in `app/js` and bundle them with their dependencies using Webpack, saving them to `public/javascripts/app/bundle`.
-1. `sass`: Compile SCSS stylesheets to CSS using `libsass`.
-1. `bless`: _(disabled by default)_ Split compiled stylesheets into chunks in order to comply with MSIE 9's stylesheet selector limit.
-
-### Custom Tasks
-
-`grunt-jade` provides a couple of custom Grunt tasks that run as part of the default task set:
-
-+ `set-jade-paths` makes Grunt's configuration aware of the ePublishing gems that a site depends on.
-  + Spawns a [Ruby script](./tasks/get-jade-gems.rb) as a subprocess that does the following things:
-    + Sets up Bundler and loads the site's RubyGems dependencies.
-    + Prints a list of gems whose names match the regular expression `/jade/` to stdout, as a JSON array.
-  + Parses the JSON array and populates `grunt.config.paths` with entries corresponding to:
-    + Jade's installation path as `paths.jade`
-    + The child gem's installation path (if any) as `paths.jadechild`
-    + Various relative asset directory paths (i.e. `paths.js_src`, `paths.css`, etc.)
-+ `npm-install` iterates through the paths populated by `set-jade-paths` looking for package.json files.
-  + If any results are found, it does the following for each:
-    + Switches the current working directory to the parent folder of the current package.json result.
-    + Runs `npm install` as a subprocess and waits for it to complete.
-  + When all results have been processed, the task changes the working directory back to the site's root.
-+ `watch-all` runs `grunt watch` and `grunt webpack --watch` at the same time in subprocesses
+---
 
-## Release Management
+## 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:
 
-`grunt-epublishing` installs the [bumped](https://bumped.github.io/) package as a development dependency, and its package.json file provides an NPM script that can be used to increment release versions, commit, tag, push, and publish to NPM in a single step:
+1. `config/build.config.js` (new)
+2. `config/grunt-config.js` (legacy, still supported)
 
-```sh
-# Example (bump patch version):
-$ npm run release patch
+Config can export a function that receives the base config:
+
+```js
+// config/build.config.js or config/grunt-config.js
+module.exports = function(baseConfig) {
+  return {
+    webpack: {
+      dist: {
+        entry: { ... },
+        output: { ... }
+      }
+    },
+    sass: { ... },
+    concat: { ... }
+  };
+};
 ```
 
+Or a plain object:
+
+```js
+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
 
-If you're working on new build system features, you can link your local clone of grunt-epublishing into a Jade site like
-so:
+To develop or debug the build tools against a Jade site:
 
-```sh
+```bash
 # Inside the grunt-epublishing directory:
 npm link
 
-# Change directories to the site:
-cd ../jade-site
-
+# 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):**
+```js
+// Gruntfile.js
+module.exports = function(grunt) {
+  grunt.loadNpmTasks('@epublishing/grunt-epublishing');
+  grunt.registerTask('default', ['jade']);
+};
+```
+```bash
+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](https://bumped.github.io/) (see `.bumpedrc`), version bumping and publishing can be automated. Otherwise, manually bump `version` in `package.json`, commit, tag, and run `npm publish`.

package/bin/epublishing-build.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+/**
+ * ePublishing Build Tools CLI
+ * 
+ * Modern replacement for grunt-epublishing.
+ * 
+ * Usage:
+ *   npx epublishing-build              # Full build
+ *   npx epublishing-build --watch      # Watch mode
+ *   npx epublishing-build webpack      # Webpack only
+ *   npx epublishing-build sass         # Sass only
+ *   npx epublishing-build concat       # Concat only
+ */
+
+'use strict';
+
+const { run } = require('../lib/cli');
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error('Build failed:', err.message);
+  if (process.env.DEBUG) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+});
+
+