wp-blank-scripts 3.1.19 → 4.0.0-alpha.1

package/README.md

@@ -1,130 +1,116 @@
 # WP Blank Scripts
 
-CLI and build tool for Wordpress projects.
+CLI and build tool for WordPress projects at ViVO Digital.
 
-## Upgrade to v3
+## Requirements
 
-Surprisingly there are no breaking changes.
-
-**v3 Warnings**
-
-#### Sass division outside of calc() deprecated
-
-Deprecation Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.
-Recommendation: math.div(-$grid-gutter, 2) or calc(-1 * $grid-gutter / 2). More info and automated migrator: https://sass-lang.com/d/slash-div
-
-Fix:
-
-```
-npm install -g sass-migrator
-sass-migrator division **/*.scss
-
-```
+- Node `>=22`
+- MAMP (optional — skipped automatically if not installed)
 
 ## Project Structure
 
+### New projects (v4+)
+
 ```
 /
-├── config
+├── config/
 │   ├── .htaccess{-environment}
 │   ├── robots{-environment}.txt
 │   └── wp-config{-environment}.php
-├── src
-│   ├── assets
-│   │   ├── admin
-│   │   ├── css
-│   │   ├── fonts
-│   │   ├── img
-│   │   └── js
-│   ├── functions.php
-│   ├── inc
-│   ├── screenshot.png
-│   ├── style.css
-│   └── templates
-├── sql
-├── tasks
+├── src/
+│   ├── blocks/
+│   ├── parts/
+│   ├── index.js
+│   ├── style.scss
+│   └── ...theme files
+├── sql/
+├── tasks/
 │   └── overrides.js
-├── vendor
-├── wordpress
-└── wp-content
+├── vendor/
+└── wp-content/
+```
+
+### Legacy projects (pre-v4)
+
+```
+/
+├── src/
+│   ├── assets/
+│   │   ├── admin/
+│   │   ├── css/
+│   │   ├── fonts/
+│   │   ├── images/
+│   │   └── js/
+│   └── ...theme files
+└── ...
 ```
 
+Both structures are auto-detected — no configuration required.
+
+---
+
 ## Usage
 
-Typically you'll use this in your npm scripts (or package scripts):
+Add to your project's `package.json` scripts:
 
 ```json
 {
   "scripts": {
-    "start": "wp-scripts dev",
-    "build": "NODE_ENV=production wp-scripts build",
+    "dev": "wp-scripts dev",
+    "build": "wp-scripts build",
+    "build:staging": "wp-scripts build --environment=staging",
+    "build:production": "wp-scripts build --environment=production",
     "import": "wp-scripts import",
     "backup": "wp-scripts backup",
     "setup": "wp-scripts setup",
     "export": "wp-scripts export",
     "deploy": "wp-scripts deploy",
-    "pull": "wp-scripts pull",
-    "clone": "wp-scripts clone"
+    "pull": "wp-scripts pull"
   }
 }
 ```
 
-### CLI
-
-#### `backup`
-
-Backup wp-content from dev project to local file system.
-
-#### `build`
-
-Build the project to the output directory
-
-**Env variables:**
-
-- `BUILD_ENV=local|staging|production` to set the build environment
-
-**Options:**
-
-**environment** `local|staging|production` (required)
+---
 
-The environment to deploy to, defaults to `process.env.BUILD_ENV`
+## CLI Commands
 
-#### `dev`
+### `dev`
 
-Run the project in dev mode with live reload server.
+Run the project in dev mode with live reload.
 
 **Env variables:**
 
-- `PORT=3001` to change dev server port to 3001
-- `HTTPS=1` to enable https for the dev server
+- `PORT=3001` — change dev server port
+- `HTTPS=1` — enable HTTPS for the dev server
+- `BYPASS_REACT=true` — force non-React mode even if `react` is in dependencies
 
-#### `deploy`
+---
 
-Build and deploy the project via SSH, with optional SQL.
+### `build`
 
-All environment information should be in `project/config/settings.json`.
+Build the project to the output directory.
 
 **Options:**
 
-**environment** `staging|production` (required)
-
-The environment to deploy to.
-
-**mode** `Site|wp-content|Theme|Plugins|SQL only` (required)
+- `--environment` `local|staging|production` — build environment (required)
 
-What should be deployed, `Site` is the entired build directory.
+When building for `staging` or `production`, output goes to `dist-{environment}` so it doesn't overwrite your local dev build. The deploy command handles cleanup automatically.
 
-**sql** `boolean`
+---
 
-Should SQL be deployed, this is assumed true if mode is `SQL only`.
+### `deploy`
 
-**serverPassword** `string`
+Build and deploy the project via rsync over SSH, with optional SQL deployment.
 
-The password for the configured user on the server. This is only required if `sql` is true and no `serverPrivateKey` is provided.
+All environment info must be in `config/settings.json`.
 
-**serverPrivateKey** `string`
+**Options:**
 
-Path to the private key for the configured user on the server. This is only required if `sql` is true and no `serverPassword` is provided.
+- `--environment` `staging|production` (required)
+- `--mode` `Site|wp-content|Theme|Plugins|SQL only` (required)
+- `--sql` `boolean` — deploy SQL (assumed true if mode is `SQL only`)
+- `--serverPassword` `string` — SSH password (if not using key)
+- `--serverPrivateKey` `string` — path to SSH private key (defaults to `~/.ssh/id_rsa`)
 
 **Example:**
 
@@ -132,15 +118,15 @@ Path to the private key for the configured user on the server. This is only requ
 wp-scripts deploy --mode="wp-content" --environment="staging"
 ```
 
-#### `export`
+---
 
-Export the local SQL database to the `project/sql` directory.
+### `export`
 
-**Options:**
+Export the local SQL database to the `sql/` directory.
 
-**environment** `local|staging|production` (required)
+**Options:**
 
-The environment you are exporting for. If not `local` urls will be replaced to those found in the config file for that environment.
+- `--environment` `local|staging|production` (required) — if not `local`, URLs are replaced with those from the config for that environment
 
 **Example:**
 
@@ -148,59 +134,38 @@ The environment you are exporting for. If not `local` urls will be replaced to t
 wp-scripts export --environment="staging"
 ```
 
-#### `import`
+---
 
-Import a local SQl file to the local database.
+### `import`
 
-Will automatically create the database if it does not exist.
+Import a SQL file into the local database. Creates the database if it doesn't exist.
 
 **Options:**
 
-**file** `path/to/file` (required)
-
-The path to the file to import.
-
-Pass `latest` instead of a file path to automatically import the most recent SQL file from the `./sql` directory.
+- `--file` `path/to/file` (required) — pass `latest` to use the most recent file in `./sql`
+- `--replace` `boolean` — replace URLs before importing (does not mutate the original file)
+- `--environment` `local|dev|staging|production` — environment to replace URLs **from**
+- `--currentEnvironment` `local|dev|staging|production` — environment to replace URLs **to**
 
-**replace** `boolean`
-
-Should urls be replaced in the SQL before importing. This will not mutate the original file.
-
-**environment** `local|dev|staging|production`
-
-The environment you are replacing the urls **from**. This is only required if `replace` is true.
-
-**currentEnvironment** `local|dev|staging|production`
-
-The environment you are replacing the urls **to**. This is only required if `replace` is true.
-
-**Example:**
+**Examples:**
 
 ```bash
 wp-scripts import --file="./sql/database.sql"
-# Import file and replace urls from staging to dev
-wp-scripts import --file="./sql/database.sql" --replace="true" --environment="staging" --currentEnvironment="dev"
-# Use the latest file
 wp-scripts import --file="latest"
+wp-scripts import --file="./sql/database.sql" --replace="true" --environment="staging" --currentEnvironment="local"
 ```
 
-#### `pull`
-
-Pull from an _environment_ database to the `project/sql` directory.
-
-**Options:**
-
-**environment** `staging|production` (required)
+---
 
-The environment you are pulling for. This will not replace urls in the file.
+### `pull`
 
-**serverPassword** `string`
+Pull a remote database to the `sql/` directory.
 
-The password for the configured user on the server. This is only required if no `serverPrivateKey` is provided.
-
-**serverPrivateKey** `string`
+**Options:**
 
-Path to the private key for the configured user on the server. This is only required if no `serverPassword` is provided.
+- `--environment` `staging|production` (required)
+- `--serverPassword` `string`
+- `--serverPrivateKey` `string`
 
 **Example:**
 
@@ -208,187 +173,149 @@ Path to the private key for the configured user on the server. This is only requ
 wp-scripts pull --environment="staging" --serverPrivateKey="~/.ssh/id_rsa"
 ```
 
-#### `setup`
+---
+
+### `setup`
 
-Setup a new _blank_ project.
+Set up a new blank project by replacing template placeholders.
 
 **Options:**
 
-**projectLocation** `string` (required)
+- `--projectLocation` `string` — path relative to MAMP document root
+- `--project` `string` — project name
+- `--productionDomain` `string` — production domain (e.g. `example.com`)
+- `--tablePrefix` `string` — WordPress table prefix
 
-_Default:_ `process.cwd`
+Running without options launches an interactive prompt.
 
-The location of the project relative to your MAMP server directory.
+---
 
-**project** `string` (required)
+### `backup`
 
-The project name
+Backup `wp-content` from the dev project to the local file system.
 
-**productionDomain** `string` (required)
+---
 
-The production domain name
+### `hooks`
 
-**agency** `string` (required)
+Run a git hook action.
 
-The name of the agency
+**Options:**
 
-**agencySlug** `string` (required)
+- `--type` `string` — hook type (e.g. `post-merge`)
 
-The slug version of the agency name
+---
 
-**agencyWebsite** `string` (required)
+### `config`
 
-The agency website url
+Add deployment config for an environment.
 
-**tablePrefix** `string` (required)
+**Options:**
 
-The table prefix for wordpress tables
+- `--environment` `staging|production`
 
-**Example:**
+---
 
-```bash
-wp-scripts setup --project="Hello"  --productionDomain="example.com" --agency="Mitch" --agencySlug="mitch" --agencyWebsite="mitch.app" --tablePrefix="mh_"
-```
+### `migrate-sass`
 
-#### `hooks`
+Migrate legacy SCSS to Dart Sass 3.0 compatible syntax using the official `sass-migrator`.
 
-Run a git hook
+Dart Sass 3.0 removes `@import`, deprecated color functions (`darken`, `lighten`), `/` for division, and global built-in functions (`map-get`, `nth`). This command runs the official migrations in a safe order.
 
 **Options:**
 
-**type** `string` (required)
+- `--migration` `division|color|module` — run a single specific migration (omit to run all three in order)
+- `--glob` `string` — SCSS file glob (default: `src/**/*.scss`)
+- `--dry-run` — preview changes without writing files
 
-The type of git hook to run.
+**Migrations (run in this order):**
 
-**Example:**
+| Migration | What it does | Risk |
+|-----------|-------------|------|
+| `division` | Replaces `/` division with `math.div()`, adds `@use 'sass:math'` | Low |
+| `color` | Replaces `darken()`/`lighten()` etc. with `color.adjust()`/`color.scale()`, adds `@use 'sass:color'` | Low |
+| `module` | Converts `@import` → `@use`/`@forward`, namespaces variables/mixins/functions | High — review carefully |
 
-```bash
-wp-scripts hooks --type="pre-commit"
-```
+**Recommended workflow:**
 
-### Upgrading from v0.3
+Node modules are resolved automatically (`--load-path=.` is passed to sass-migrator), so imports like `@import 'node_modules/swiper/css/swiper.min'` are handled correctly.
 
-There are multiple breaking changes since v0.3, including a new build system.
+```bash
+# 1. Preview what will change
+wp-scripts migrate-sass --dry-run
 
-Run the upgrade script in the project:
+# 2. Run the safe migrations first
+wp-scripts migrate-sass --migration=division
+wp-scripts migrate-sass --migration=color
 
-```bash
-node_modules/.bin/wp-scripts upgrade
-```
+# 3. Verify your build still works, then commit
+yarn build
 
-_Note: Make sure you have committed everything before upgrading._
+# 4. Run the module migration separately — requires manual review
+#    Variables will be namespaced (e.g. $var → variables.$var)
+wp-scripts migrate-sass --migration=module
+```
 
-### Overrides
+The `module` migration is complex and almost always requires manual cleanup — especially if partials are imported in multiple places. Run it last and review every changed file before committing.
 
-You can export custom functions to override the default build behaviour.
+---
 
-Just create an `tasks/overrides.js` file in the project.
+## Overrides
 
-#### `copyFiles`
+Create a `tasks/overrides.js` file in your project to customise the build.
 
-Add extra files to the build copy task.
+### `copyFiles`
 
-See [copy-webpack-plugin](https://github.com/webpack-contrib/copy-webpack-plugin) for more details.
+Add extra files to the webpack copy task.
 
-```
+```js
 exports.copyFiles = (paths) => {
-  // The paths object contains source, theme and build paths.
-  const {
-    sourceDir, // Relative
-    themeDir, // Relative
-    sourcePath, // Absolute
-    buildPath, // Absolute
-    themePath, // Absolute
-  } = paths;
+  const { sourceDir, themeDir, sourcePath, buildPath, themePath } = paths;
 
   return [
     {
-      // Copy an entire directory to the theme
-      from: path.join(sourceDir, 'new-directory'),
-      to: path.join(themePath, 'new-directory'),
+      from: path.join(sourceDir, 'my-directory'),
+      to: path.join(themePath, 'my-directory'),
     },
-    {
-      // Copy files inside a directory the the theme
-      from: path.join(sourceDir, 'new-directory'),
-      to: themePath,
-    },
-    {
-      // Copy file from a directory to the root directory
-      from: path.join(sourceDir, 'directory-file-was-in', 'file.txt'),
-      to: '',
-    },
-    {
-      // Copy all files from vendor (except vivo-digital & johnpbloch) to the theme/inc/vendor
-      from: path.join(__dirname, "..", "vendor"),
-      to: path.join(themePath, "inc", "vendor"),
-      globOptions: {
-        ignore: [
-          path.join("@(vivo-digital|johnpbloch)", '**')
-        ],
-      }
-    }
   ];
-}
+};
 ```
 
-#### `webpackConfig`
+### `webpackConfig`
 
-Overide the default webpack config.
+Override the default webpack config (merged via webpack-merge).
 
-```
+```js
 exports.webpackConfig = () => {
   return {
-    // Disable sourcemaps completely
     devtool: false,
-  }
-}
+  };
+};
 ```
 
-#### `loaderOptions`
+### `loaderOptions`
 
-Overide default loader options. This is useful in cases where you want to alter an existing loader and cannot use a custom `webpackConfig`.
+Override default loader options. Available loaders: `css`, `js`, `images`, `fonts`.
 
-Available loaders: `css`, `js`, `images`, `fonts`
-
-```
+```js
 exports.loaderOptions = () => {
   return {
     js: {
-      // Don't run js files from node_modules OR vendor directories through the JS (babel) loader
       exclude: /(node_modules|vendor)/,
-    }
+    },
   };
 };
 ```
 
-#### `copyFx`
-
-You can change the path of `fx` packages (classes or modules) installed via composer. This is useful for local development.
-
-This function should return an object with the package name as the key and local path as the value.
-
-```
-exports.copyFx = () => {
-  return {
-    'package-name': 'path/to/local/repository',
-  };
-}
-```
-
-#### `checkProjectDependencies`
+### `checkProjectDependencies`
 
 Run a custom dependency check before the project builds.
 
-```
-exports.checkProjectDependencies = () => {
-  const pck = JSON.parse(fs.readFileSync(projectPackage, 'utf8'));
-  const { dependencies } = pck;
-
-  if (!dependencies['some-required-package']) {
-    console.log('Missing this package!');
+```js
+exports.checkProjectDependencies = async () => {
+  const pck = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  if (!pck.dependencies['some-required-package']) {
+    console.warn('Missing some-required-package!');
   }
 };
 ```
-
-## Node Version
-Currently supports `18.8.0` for all projects running `wp-blank-scripts@3.0.0`

package/cli/config.js

@@ -63,12 +63,12 @@ module.exports = async () => {
       },
       {
         name: 'urlProduction',
-        message: 'What is the production URL?',
+        message: 'What is the production URL? (https://...)',
         when: (answers) => answers.environment === 'production',
       },
       {
         name: 'hostProduction',
-        message: 'What is the production server host?',
+        message: 'What is the production server host? (example.com)',
         when: (answers) => answers.environment === 'production',
       },
       {
@@ -102,20 +102,20 @@ module.exports = async () => {
       },
       {
         name: 'urlStaging',
-        message: 'What is the staging URL?',
+        message: 'What is the staging URL? (https://...)',
         when: (answers) => answers.environment === 'staging',
       },
       {
         name: 'hostStaging',
-        message: 'What is the staging server host?',
+        message: 'What is the staging server host? (example.com)',
         when: (answers) => answers.environment === 'staging',
-        default: 'staging.vivo.digital',
+        default: 'preview.vivo.digital',
       },
       {
         name: 'userStaging',
         message: 'What is the staging server user?',
         when: (answers) => answers.environment === 'staging',
-        default: 'stagingvivo',
+        default: 'previewv',
       },
       {
         name: 'destinationStaging',

package/cli/deploy.js

@@ -43,11 +43,11 @@ async function selectOptions() {
       message: chalk.cyan('Do you want to deploy sql?'),
       type: 'confirm',
       default: false,
-      when: answers => answers.mode !== DEPLOY_MODES.SQL_ONLY,
+      when: (answers) => answers.mode !== DEPLOY_MODES.SQL_ONLY,
     },
     {
       name: 'serverPassword',
-      message: answers => {
+      message: (answers) => {
         const user = settings.server[answers.environment].user;
         const host = settings.server[answers.environment].host;
         return chalk.cyan(
@@ -55,18 +55,18 @@ async function selectOptions() {
         );
       },
       type: 'password',
-      when: answers => answers.sql || answers.mode === DEPLOY_MODES.SQL_ONLY,
+      when: (answers) => answers.sql || answers.mode === DEPLOY_MODES.SQL_ONLY,
     },
     {
       name: 'serverPrivateKey',
-      message: answers => {
+      message: (answers) => {
         const user = settings.server[answers.environment].user;
         const host = settings.server[answers.environment].host;
         return chalk.cyan(`Enter the path to your private key for user ${user} on host ${host}`);
       },
       default: '~/.ssh/id_rsa',
       type: 'input',
-      when: answers => !answers.serverPassword,
+      when: (answers) => !answers.serverPassword,
     },
   ]);
 
@@ -84,7 +84,7 @@ async function selectOptions() {
 }
 
 async function confirmOptions(selectedOptions) {
-  const deploymentOptinos = [
+  const deploymentOptions = [
     ['Environment', selectedOptions.environment],
     ['Mode', selectedOptions.mode],
     ['SQL', selectedOptions.sql || selectedOptions.mode === DEPLOY_MODES.SQL_ONLY],
@@ -93,7 +93,7 @@ async function confirmOptions(selectedOptions) {
   const { confirm } = await inquirer.prompt([
     {
       name: 'confirm',
-      message: `Please confirm your project settings:\n${deploymentOptinos
+      message: `Please confirm your project settings:\n${deploymentOptions
         .map(([title, value]) => `${chalk.yellow(title)}: ${value}`)
         .join('\n')}`,
       type: 'confirm',
@@ -126,7 +126,7 @@ async function promptForCommit(options, unstagedFiles) {
       name: 'message',
       message: chalk.cyan('Commit message'),
       default: `Deploying to ${options.environment}`,
-      when: answers => answers.commit,
+      when: (answers) => answers.commit,
     },
   ]);