Skip to content

Commit

Permalink
Add NPM workspaces, build using out of the box wp-scripts (#506)
Browse files Browse the repository at this point in the history 
* Add npm workspaces, lint globally, build locally

* Run script only if present

* Move postcss back out to global setup

* Add extensions

* Add back missing postcss packages

* Merge old and new postcss config

* stylelint-order can be added separately later

* Add back unused theme-json packages

* Move unused theme-json setup into theme

* Disable theme-json generation. No src files in theme

* No need for default config

* Rename dev script back to start

* Remove entryFiles discovery from global webpack config

* install comment is depreacted in huskey 9+

* Remove outdated postcss-flexbugs-fixes plugin, no more need for this

* No Turbo cache folder, yet

* Update installation readme

* Add blueprint plugin

* Update wp-scripts to v28

* Optimize docs (INSTALLATION.md) (#507)

* Optimize docs

* Link wp-scripts

---------

Co-authored-by: Stian <stian.overasen@dekode.no>

* More readme on wp-scripts

* tweaks

---------

Co-authored-by: Ole Thomas Tallerås <olethomas@dekode.no>
  • Loading branch information
@stian-overasen @olethomas
stian-overasen and olethomas authored Jun 25, 2024
1 parent 168371f commit 6f5474d
Show file tree
Hide file tree
Showing 28 changed files with 4,405 additions and 20,501 deletions.
1 change: 1 addition & 0 deletions .eslintrc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ module.exports = {
'@wordpress/no-global-event-listener': 'off',
'@wordpress/dependency-group': 'error',
'@wordpress/no-unsafe-wp-apis': 'error',
'react-hooks/rules-of-hooks': 'off',
},
parser: '@babel/eslint-parser',
parserOptions: {
Expand Down
315 changes: 191 additions & 124 deletions INSTALLATION.md
View file
Original file line number Diff line number Diff line change
@@ -1,136 +1,203 @@
# Dekode Project Base - Installation
# Dekode Project Base - Installation Guide

## Requirements

* PHP >= 8.2
* Composer - [Install](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)
* Node = 18.0

## TLDR - what's new?
Themes, plugins, mu-plugins etc. is now structured under packages and built into the wordpress structure by composer. All build scripts are run from root and automatically looks through `./packages`. Packages need an `entry-files.json` file to define what files should be build when running npm build/start and a `composer.json` that defines what it is and gives the package a name. Codeship testing/build commands are now located in the repository under `./tools`. Any time a new package is added it needs to be referenced in the project-base root composer.json using @dev.

## Structure
* *Packages* - Contains all of the code developed for the project such as plugins, themes, mu-plugins and any custom libs etc. This gets built into public by composer using symlinks.
* *Public* - The files used by WordPress. Contents are generated automatically from packages using composer. This folder shouldn't need to be touched at all.
* *Tools* - Build and setup scripts used by Codeship and Local
* *Config* - Environment variable setup

## Local setup
1. If setting up a new project, create a git repo using [Project base](https://github.com/DekodeInteraktiv/project-base) as the template. Otherwise skip this step.
2. Create a new site in Local by Flywheel, make sure that you enable multisite (subdir) if relevant for the project.
3. Follow one of the methods below (not both!)

### Method 1 - Setup replicating server structure
4. `cd app` go inside the app folder
5. `rm -rf public` remove the default public folder
6. `git clone git@github.com:DekodeInteraktiv/{YOUR_PROJECT} .` clone the project into the current folder (the . is important)
7. `cp .env.example .env` copy the environment example file (do not rename it, as it will show as git differences)
8. Update the environment variables in the .env file

* `DB_NAME` - Database name
* `DB_USER` - Database user
* `DB_PASSWORD` - Database password
* `DB_HOST` - Database host
* `WP_ENVIRONMENT_TYPE` - Set to environment (`local`, `development`, `staging`, `production`)
* `WP_HOME` - Full URL to WordPress home (http://example.com)
* `WP_SITEURL` - Full URL to WordPress including subdirectory (http://example.com/wp)
* `AUTH_KEY`, `SECURE_AUTH_KEY`, `LOGGED_IN_KEY`, `NONCE_KEY`, `AUTH_SALT`, `SECURE_AUTH_SALT`, `LOGGED_IN_SALT`, `NONCE_SALT`

9. Automatically generate the security keys

If you want to automatically generate the security keys (assuming you have wp-cli installed locally) you can use the very handy [wp-cli-dotenv-command](https://github.com/aaemnnosttv/wp-cli-dotenv-command):

- wp package install aaemnnosttv/wp-cli-dotenv-command
- wp dotenv salts regenerate

Or, you can cut and paste from the [Roots WordPress Salt Generator](https://roots.io/salts.html).

10. `composer install`
11. `npm ci`
12. Run the app/tools/local scripts (please note that these might work only if you setup the `MYSQLI_DEFAULT_SOCKET` environment variable, and only after you actually have the plugins and theme installed at step 10).

* `cd app/tools/local`
* `./setup-main-site.sh`
* `./activate-plugins.sh`
* `bash multisite.sh` (run this only if you are installing a multisite)

13. If you install a multisite, the URLs are not using https by default, and that can be fixed by running the command `wp search-replace --url=http://{PROJECT}.site 'http://{PROJECT}.site' 'https://{PROJECT}.site' --recurse-objects --network --skip-columns=guid`

### Method 2 -Setup using Local structure (symlink method)

4. `cd` to the site app folder and clone the existing project (or the one you setup on step 1) from github.
5. `cd` into public and remove wp-content `rm -rf wp-content`
6. create a symlink in public from `wp-content` to `../{project folder}/public/content`
7. Run the scripts in `./tools/local/`

### wp-cli and Local by Flywheel

To be able to use wp-cli, you can use [Local by Flywheel](https://localwp.com/) build-in in site shell.

If you would like to access the wp-cli in the defauly system console there can be issues trying to use wp-cli commands when using a [Local by Flywheel](https://localwp.com/) development environment. You can usually fix this with the following steps:

1. Add a file named `wp-cli.local.yml` to the root (`app`) directory, with the following content:

- **PHP**: Version 8.2 or higher
- **Composer**: [Install Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)
- **Node.js**: Version 18.0

## Project Structure

- **Packages**: Contains all project-specific code such as plugins, themes, mu-plugins, and custom libraries. These are built into the `public` directory using symlinks via Composer.
- **Public**: Contains files used by WordPress, automatically generated from packages by Composer. This folder should not be modified manually.
- **Tools**: Contains build and setup scripts used by Codeship and Local.
- **Config**: Contains environment variable setup files.

## Local Setup

### Initial Setup

1. **Create a Git Repository**:
- If setting up a new project, create a git repository using [Project Base](https://github.com/DekodeInteraktiv/project-base) as the template.

2. **Create a New Site in Local**:
- Enable multisite (subdirectory) if applicable to the project.

### Setup Methods

#### Method 1: Replicating Server Structure

1. Navigate to the app folder:
```bash
cd app
```

2. Remove the default public folder:
```bash
rm -rf public
```

3. Clone the project into the current folder:
```bash
git clone git@github.com:DekodeInteraktiv/{YOUR_PROJECT} .
```

4. Copy the environment example file:
```bash
cp .env.example .env
```

5. Update environment variables in the `.env` file:
- `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`
- `WP_ENVIRONMENT_TYPE` (local, development, staging, production)
- `WP_HOME` (e.g., `http://example.com`)
- `WP_SITEURL` (e.g., `http://example.com/wp`)
- `AUTH_KEY`, `SECURE_AUTH_KEY`, `LOGGED_IN_KEY`, `NONCE_KEY`, `AUTH_SALT`, `SECURE_AUTH_SALT`, `LOGGED_IN_SALT`, `NONCE_SALT`

6. Generate security keys (optional, requires wp-cli):
```bash
wp package install aaemnnosttv/wp-cli-dotenv-command
wp dotenv salts regenerate
```
Or use the [Roots WordPress Salt Generator](https://roots.io/salts.html).

7. Install Composer dependencies:
```bash
composer install
```

8. Install npm dependencies:
```bash
npm ci
```

9. Run local setup scripts (ensure `MYSQLI_DEFAULT_SOCKET` is set if needed):
```bash
cd app/tools/local
./setup-main-site.sh
./activate-plugins.sh
bash multisite.sh # Only for multisite setup
```

10. Update URLs for multisite to use HTTPS:
```bash
wp search-replace --url=http://{PROJECT}.site 'http://{PROJECT}.site' 'https://{PROJECT}.site' --recurse-objects --network --skip-columns=guid
```

#### Method 2: Using Local Structure (Symlink Method)

1. Navigate to the site app folder and clone the project:
```bash
cd path/to/app
git clone git@github.com:DekodeInteraktiv/{YOUR_PROJECT} .
```

2. Remove the default `wp-content` folder:
```bash
rm -rf public/wp-content
```

3. Create a symlink for `wp-content`:
```bash
ln -s ../{project folder}/public/content public/wp-content
```

4. Run local setup scripts:
```bash
cd tools/local
./setup-main-site.sh
./activate-plugins.sh
bash multisite.sh # Only for multisite setup
```

## Using wp-cli with Local

To use wp-cli with Local, you can use the built-in site shell. For default system console access, add a `wp-cli.local.yml` file to the root (`app`) directory:
```yml
path: public/wp
require:
- wp-cli-local.php
```

2. Set the `MYSQLI_DEFAULT_SOCKET` in the `.env` file.

To obtain `MYSQLI_DEFAULT_SOCKET` with the socket path from the corresponding project in Local, which can be found in the **Database** tab (local app) and usually looks something like the following (on Mac OS):

`/Users/<username>/Library/Application Support/Local/run/<unique string>/mysql/mysqld.sock`

## Installation and build
Run `composer install` and `npm ci && npm run build` in root to build the project.
Set the `MYSQLI_DEFAULT_SOCKET` in the `.env` file using the path from the Local Database tab.

### Extending the builds
Project-base uses wp-scripts to build front end assets using the `npm run build` or `npm run start` commands. wp-scripts in turn uses webpack and postcss. You can extend those by editing the postcss.config.js and webpack.config.js files.
## Installation and Build

## Adding a new package (ex. plugin/mu-plugin/theme)
1. Add a folder to the relevant category in `./packages`. (create one if none exists). So for a plugin, create a folder in the `./packages/plugins` folder.

2. If your package should be installed using composer (for themes, plugins, mu-plugins and php deps) Add a composer.json, it needs a minimum of the following data:
```json
{
"name": "project/package-name",
"description": "Short description of the package.",
"type": "wordpress-plugin/wordpress-muplugin/wordpress-theme/other",
"version": "1.0.0"
}
```
*Note: if your plugin is a gutenberg block, you can use [block-base](https://github.com/DekodeInteraktiv/block-base)*

*Note: A version should _always_ be supplied. This ensures that package versions do not change between branches, leading to unneccesary merge conflicts.*

3. If your package should be installed using npm (for frontend deps, like custom react components) Add a package.json, it needs a minimum of the following data:

```json
{
"name": "package-name",
"private": true,
"version": "1.0.0",
"description": "Package description",
"author": "Dekode",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
}
}
```

4. If your package has front end assets such as scripts or css add a `entry-files.json` with the following structure naming the src files that should be build. (the src files should be located in a folder called `src`)
```json
[ "index.js", "style.css", "editor.css" ]
Run the following commands in the root directory to build the project:
```bash
composer install
npm ci && npm run build
```

5. Go back to the project root and update the composer.json or package.json depending on package type. For composer add a entry under "require" like such `"project/package-name": "@dev"`. For package.json add an entry under "devDependencies" like such `"package-name": "file:packages/folder/package-name"`.

6. Install the package using `composer update` or `npm install` depending on type. you might need to re-run `npm run build` or `npm run start` if you have installed a new package containing files that need building.

## Documentation
* PostCSS [https://github.com/postcss/postcss/tree/main/docs](https://github.com/postcss/postcss/tree/main/docs)
* WebPack [https://webpack.js.org/concepts/](https://webpack.js.org/concepts/)
* WP Scripts [https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
(See `packages/themes/dekode-theme` or `packages/plugins/blueprint` for more details)

## Extending Builds

Project Base uses [wp-scripts](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts) out of the box for building front-end/view and editor assets. wp-script will scan all `block.json` files in the `src/` folder to find available entries. This means that if you have a `src` folder with a `view.js` and a `editor.js`, you also need to add a `block.json` file at the same location. Have a look in the `dekode-theme` theme or the `blueprint` plugin for examples or read up on [wp-script auto discovery for Webpack entry points](https://github.com/WordPress/gutenberg/blob/trunk/packages/scripts/utils/config.js#L198). For a more advanced setup, you can always customize builds by adding your own `webpack.config.js`.

### A quick overview of wp-scripts auto discovery:
1. Supply entry points manully to the CLI, e.g. `wp-scripts build src/view src/editor src/admin src/some-other-entry`. This will bypass 2 and 3.
2. Scan `src` folder for all `block.json` files. (Our default setup). This will support both theme/plugin assets (view/editor) and possible blocks inside the `src/` folder.
3. Fallback to `src/index.*` file. This will only look for a `src/index.js` file.

## Adding a new package (plugin, mu-plugin or theme)

1. **Create a folder**: Add a folder in `./packages` (e.g., `./packages/plugins`).

2. **Add a `composer.json` File** (for themes, plugins, mu-plugins, and PHP dependencies):
```json
{
"name": "project/package-name",
"description": "Short description of the package.",
"type": "wordpress-plugin/wordpress-muplugin/wordpress-theme/other",
"version": "1.0.0"
}
```

*Note: Use [block-base](https://github.com/DekodeInteraktiv/block-base) for Gutenberg blocks.*

*Note: A version should always be supplied. This ensures that package versions do not change between branches, leading to unneccesary merge conflicts.*

3. **Add a `package.json` File** (for frontend dependencies or custom React components):
```json
{
"name": "package-name",
"private": true,
"version": "1.0.0",
"description": "Package description",
"author": "Dekode",
"main": "index.js",
"scripts": {
"build": "echo \"Error: no build specified\" && exit 1",
"start": "echo \"Error: no start specified\" && exit 1",
"test": "echo \"Error: no test specified\" && exit 1",
"clean": "rm -rf node_modules build dist"
}
}
```

4. **Update Root Configuration**:
- For Composer packages, add an entry under `"require"` in `composer.json`:
```json
"project/package-name": "@dev"
```
- For npm packages, add an entry under `"devDependencies"` in `package.json`:
```json
"package-name": "file:packages/folder/package-name"
```

5. **Install the Package**:
- For Composer:
```bash
composer update
```
- For npm:
```bash
npm install
```
Re-run `npm run build` or `npm run start` if needed.

## Additional Documentation

- **PostCSS**: [PostCSS Documentation](https://github.com/postcss/postcss/tree/main/docs)
- **WebPack**: [WebPack Concepts](https://webpack.js.org/concepts/)
- **WP Scripts**: [WP Scripts Guide](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
1 change: 1 addition & 0 deletions composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"php": ">=8.2",
"boxuk/wp-muplugin-loader": "~2.2.0",
"composer/installers": "~2.2.0",
"dekode/blueprint": "~1.0.0",
"dekode/dekode-theme": "~1.0.0",
"dekode/imagify-helper": "1.0.0",
"dekodeinteraktiv/dekode-label-environment": "~1.0.0",
Expand Down
Loading

0 comments on commit 6f5474d

Please sign in to comment.