README

# Theme Readme - DesignHammer

---

## Install

Install the following node modules (npm), in the same directory as this readme file, for compiling and linting our code.

```bash
npm i -D | bun add -D autoprefixer browser-sync concurrently nodemon postcss postcss-cli postcss-pxtorem sass standard stylelint stylelint-config-sass-guidelines stylelint-order uglify-js
```

A brief explanation for the following four scripts piped together.

- style:sass - Standard Sass CLI but with no output file.
- style:perl - Replaces Sass soucremap source urls from absolute to relative.
- style:postcss - Standard PostCSS CLI using config for plugins, but with no input file.
- style - Brings it altogether using CLI std/in/out so it only writes to the file system once on save.

```json
"style:sass": "sass --error-css --embed-source-map ./scss/style.scss",
"style:perl": "perl -pe 's|file:(.+?)/scss|../scss|g'",
"style:postcss": "postcss --config './postcss.config.js' -o ./css/style.css",
"style": "bun style:sass | bun style:perl | bun style:postcss",
```

---

## Config

**bsync.config file:**

- Duplicate `bsync.config.sample.js` file and rename it `bsync.config.js`.
- Change values in file as needed.
- ⚠️ Do not commit this file to the repo. It's for your local dev env only.

---

## Linting

We'll also be linting our Sass and Javascript in order to produce well written and consistent code.

Required lint files (should be added during initial theme setup):

- .eslintrc.json
- .stylelint.json
- .stylelintignore

To do a global lint on the SCSS files run: `npx stylelint "scss/**/*.scss"`. To fix found errors add the `--fix` flag.

---

## Editor

**Sublime:** install the following packages using package control:

- SublimeLinter
- SublimeLinter-contrib-standard
- SublimeLinter-eslint
- SublimeLinter-stylelint

**VS Code:** install the following extensions:

- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
- [stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)

Workspace setting should be located at the root of this project's repo: `/.vscode/settings.json`

```json
{
  "files.trimTrailingWhitespace": true,
  "eslint.workingDirectories": [
    "htdocs/themes/THEMENAME"
  ],
  "stylelint.configBasedir": "htdocs/themes/THEMENAME",
  "stylelint.configFile": "htdocs/themes/THEMENAME/.stylelintrc.json",
  "stylelint.snippet": [
    "sass",
    "scss"
  ],
  "stylelint.validate": [
    "sass",
    "scss"
  ],
  "phpsab.fixerEnable": true,
  "phpsab.snifferEnable": true,
  "phpsab.standard": "Drupal",
  "phpsab.executablePathCS": "./vendor/bin/phpcs",
  "phpsab.executablePathCBF": "./vendor/bin/phpcbf"
}
```

### Installing [PHP Code Sniffer](https://docs.designhammer.net/guides/coding-standards/) for Drupal

Run the following command from the root directory of this repo.

```bash
$ composer require --dev --with-all-dependencies drupal/coder
# set phpcs paths to Drupal, DrupalPractice
$ vendor/bin/phpcs --config-set installed_paths vendor/drupal/coder/coder_sniffer
```

To test if phpcs includes the correct sniffer, run `vendor/bin/phpcs -i`, and you should see `Drupal`, and `DrupalPractice` added to the coding standards list.

---

### Installing [PHP Code Sniffer](https://docs.designhammer.net/guides/coding-standards/) for WordPress

Run the following command from the root directory of this repo.

```bash
$ composer require --dev squizlabs/php_codesniffer wp-coding-standards/wpcs
# required plugin
$ composer require --dev dealerdirect/phpcodesniffer-composer-installer
# set phpcs paths to WordPress PHP Coding Standards
$ vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs
```

Known issue when running php 8.x:

The [WordPress Coding Standards for PHP_CodeSniffer](https://github.com/WordPress/WordPress-Coding-Standards) (`wp-coding-standards/wpcs`) package throws a deprecation notice when using PHP 8.1. They recommend using the 'develop' branch until version 3.0 comes out. In order to use a branch instead of a tag in composer, install the package as you normally would, then rename the version number to "dev-BRANCHNAME" and run `composer update`. In this case, the branch version is "dev-develop".

bookmarks

## scripts

- [Sass CLI](https://sass-lang.com/documentation/cli/dart-sass)
- [PostCSS CLI](https://github.com/postcss/postcss-cli)
- [Autoprefixer](https://github.com/postcss/autoprefixer)
- [UglifyJS](https://github.com/mishoo/UglifyJS)
- [Nodemon](https://github.com/remy/nodemon)
- [concurrently](https://github.com/open-cli-tools/concurrently)

To run sass-migrator on a file, run the following command
` npx sass-migrator module --verbose src/sass/DIR/FILE.scss `


## BrowserSync

- [Command Line Usage](https://browsersync.io/docs/command-line)
- [Options](https://browsersync.io/docs/options)

```json
"watch": "browser-sync start --no-open --no-ui --no-ghost-mode --port 3470 --proxy 'http://local10.designhammer.test' --files='./css/*.css'"
"watch": "browser-sync start --config './bs-config.js'"
```

## Nodemon

```json
"watch:styles": "nodemon -w ./scss -e scss -x 'yarn build:styles'",
"watch:scripts": "nodemon -w ./js/scripts.js -e ./js/*.js -x 'yarn scripts'",
```

bsync.config.sample.js

/*
|--------------------------------------------------------------------------
| Browser-sync config file
|--------------------------------------------------------------------------
|
| For up-to-date information about the options:
|   http://www.browsersync.io/docs/options/
|
| There are more options than you see here, these are just the ones that are
| set internally. See the website for more info.
*/

module.exports = {
  port: 3470,
  proxy: 'local.example.test',
  open: false,
  browser: 'google chrome',
  ghostMode: false,
  notify: true,
  ui: false,
  reloadOnRestart: true,
  files: [
    './css/styles.css',
    './js/scripts.js'
  ],
  snippetOptions: {
    // Load Browsersync inject code before the closing body tag
    // in-order to avoid issues with D10's admin toolbar.
    rule: {
      match: /<\/body>/i,
      fn: function (snippet, match) {
        return snippet + match
      }
    }
  }
}

build.map.js

/**
 * build.map
 *
 * When piping Sass to stdout, source-map source urls are absolute, which
 * displays the full local path as "file:///Users/username/...". This
 * script replaces the source urls with relative paths.
 *
 * Run from package.json script as:
 * "regexmap": "node -e \"require('./build.map').sassSources()\"",
 *
 * @author <frank@designhammer.com>
 */

const fs = require('fs').promises

// Change variables below to match local env.
const path = {
  style: {
    srcDir: 'scss',
    map: './css/style.css.map'
  }
}

// RegExp function.
async function sassSources () {
  const reg = new RegExp(String.raw`file:(?<=file:).+?\/${path.style.srcDir}`, 'g')
  const data = await fs.readFile(path.style.map, 'utf8')
  const result = data.replace(reg, `../${path.style.srcDir}`)

  await fs.writeFile(path.style.map, result, 'utf8')
}

module.exports = { sassSources }

gitignore

!.eslintrc.json
!README.md
node_modules
bsync.config.js

NPM Update

# [NPM Check Updates](https://www.npmjs.com/package/npm-check-updates)

- Install the tool `npm i -D npm-check-updates`
- Update the package.json `npx ncu --upgrade`
- Install the new packages npm install

package.json

{
  "name": "designhammer-website",
  "version": "0.1.0",
  "description": "Custom Drupal Theme",
  "author": "DesignHammer, LLC",
  "license": "GPL-2.0 AND MIT",
  "repository": {
    "type": "git",
    "url": "https://bitbucket.org/designhammer/dh-website"
  },
  "scripts": {
    "serve": "browser-sync start --config './bsync.config.js'",
    "style": "sass --error-css --source-map ./src/sass/styles.scss ./assets/css/styles.css",
    "postcss": "postcss ./assets/css/styles.css --use autoprefixer --map --replace",
    "script": "uglifyjs ./src/js/scripts.js --output ./assets/js/scripts.js --compress --source-map 'url=\"script.min.js.map\"'",
    "build:style": "npm run style && npm run postcss",
    "build": "npm run build:style && npm run script",
    "onchange:style": "nodemon --watch ./src/sass/ --ext scss --exec 'npm run style' --quiet",
    "onchange:script": "nodemon --watch ./src/js/ --ext js --exec 'npm run script' --quiet",
    "watch": "concurrently --raw --kill-others 'npm run serve' 'npm run onchange:style' 'npm run onchange:script'"
  },
    "browserslist": [
    "> 0.2%",
    "last 2 version",
    "Firefox ESR",
    "not dead"
  ]
}

package.json (new)

{
  "name": "designhammer-website",
  "version": "0.1.0",
  "description": "Custom Theme",
  "author": "DesignHammer, LLC",
  "license": "GPL-2.0 AND MIT",
  "repository": {
    "type": "git",
    "url": "https://bitbucket.org/designhammer"
  },
  "scripts": {
    "serve": "browser-sync start --config './bsync.config.js'",
    "style:sass": "sass --error-css --embed-source-map ./scss/style.scss",
    "style:perl": "perl -pe 's|file:(.+?)/scss|../scss|g'",
    "style:postcss": "postcss --config './postcss.config.js' -o ./css/style.css",
    "style": "bun style:sass | bun style:perl | bun style:postcss",
    "script": "uglifyjs ./src/js/scripts.js --output ./assets/js/scripts.js --compress --source-map 'url=\"script.min.js.map\"'",
    "build": "npm run style && npm run script",
    "watch:style": "nodemon --watch ./src/sass/ --ext scss --exec 'npm run style' --quiet",
    "watch:script": "nodemon --watch ./src/js/ --ext js --exec 'npm run script' --quiet",
    "watch": "concurrently --raw --kill-others 'npm run serve' 'npm run watch:style' 'npm run watch:script'"
  },
    "browserslist": [
    "> 0.2%",
    "last 2 version",
    "Firefox ESR",
    "not dead"
  ]
}

postcss.config.js

module.exports = {
  map: {
    annotation: true,
    inline: false
  },
  plugins: [
    require('postcss-pxtorem')({
      rootValue: 16,
      mediaQuery: true,
      selectorBlackList: [/^html$/, /^body$/]
    }),
    require('autoprefixer')()
  ]
}