Skip to content

npm-wordpress
npm-wordpress

Home

Last edited by Vadym Gidulian
Page history

npm-wordpress

Description

Project will be deployed to server and processed with npm and gulp.

npm is also used for dependency management and local testing. Docker and Docker Compose are used to provide WordPress installation, server and MySQL.

Project structure

Default project structure is the following:

.
├── .docker
|   ├── html
|   └── mysql
├── dist
|   ├── css
|   |   └── style.all.min.css
|   ├── img
|   ├── js
|   |   └── script.all.min.js
|   ├── index.php
|   ├── *.php
|   └── *
|       └── *.php
├── src
|   ├── css
|   |   └── *.css
|   ├── img
|   ├── js
|   |   ├── functions.js
|   |   └── index.js
|   ├── less
|   |   ├── global.less
|   |   ├── index.less
|   |   ├── media.less
|   |   └── style.less
|   ├── pug
|   |   ├── includes
|   |   |   └── mixins.pug
|   |   └── php
|   |       ├── index.pug
|   |       ├── *.pug
|   |       └── *
|   |           └── *.pug
|   ├── index.php
|   ├── style.css
|   ├── *.php
|   └── *
|       └── *.php
├── .env
├── .gitignore
├── .gitlab-ci.yml
├── bs-config.js
├── docker-compose.yml
├── gulpfile.js
└── package.json
  • .docker contains Docker containers' data
    • .docker/html contains WordPress installation
    • .docker/mysql contains MySQL data files
  • dist is theme folder located at wp-content/themes/$THEME_NAME inside WordPress installation folder ($THEME_NAME is got from .env file)
  • dist/css/style.all.min.css is CSS styles file. All styles will be compiled to it
  • dist/img is a folder for images. It will be moved as is
  • dist/js/script.all.min.js is JS script file. All scripts will be compiled to it
  • dist/index.php is main PHP file
  • dist/**/*.php are other PHP files. Their paths relative to src or src/pug/php parent folder will be preserved in dist folder
  • src/css folder is supposed to be only used as CSS libraries folder
  • src/img folder is used for images. It will be moved as is
  • src/js folder is used for JS scripts
    • src/js/index.js is main file for scripts. All other JS files should be imported to it
    • src/js/functions.js is auxiliary file and supposed to be used for JS functions. All functions necessary in other files should be exported
  • src/less folder is used for LESS styles
    • src/less/global.less is auxiliary LESS file and supposed to be used for global styles
    • src/less/index.less is main file. All other styles should be imported to it
    • src/less/media.less is auxiliary LESS file and supposed to be used for styles for different media types/devices
    • src/less/style.less is primary LESS file for styles
  • src/pug folder is used for Pug files
    • src/pug/includes are auxiliary Pug files and supposed to be used for including, mixins, templates etc. These files will not be compiled by Pug compiler
      • src/pug/includes/mixins.pug is auxiliary Pug file and supposed to be used for mixins
    • src/pug/php are Pug files that will be compiled by Pug compiler and their extension will be changed to .php
      • src/pug/php/index.pug is main Pug file that will become main PHP file
      • src/pug/php/**/*.pug are other Pug files that will be compiled by Pug compiler and their extension will be changed to .php. Their paths relative to src/pug/php folder will be preserved in dist folder
  • src/index.php is main PHP file
  • src/style.css is main CSS file. It should only contain meta information about theme, all styles should be written in corresponding files in src/less and src/css folders
  • src/**/*.php are other PHP files. Their paths relative to src folder will be preserved in dist folder
  • .env contains variables for Docker Compose config file
  • .gitignore is used to ignore files. dist folder is ignored
  • .gitlab-ci.yml is a CI config. Should not be edited in most of cases
  • bs-config.js is a Browsersync settings
  • docker-compose.yml is a Docker Compose config file
  • gulpfile.js is a gulp config. In paths.files variable inside it can be specified files and folders that will be moved to dist folder as is
  • package.json is main file for npm. Project dependencies can be specified inside it

Note: All markup files will be processed in parallel and therefore their relative paths should not be duplicated. Be aware: in the above project structure files src/index.php and src/pug/php/index.pug do have the same relative paths!

How to get

  1. Download it manually or get it using project-template-loader:

project-template-loader web/npm-wordpress

2. Open `package.json` and change `name` and `version` to the name and version of your project
3. Open `.env` and change `THEME_NAME` to the desired theme folder name
4. Open `src/style.css` and change `Theme Name` and `Description` to the name and description of your theme
5. Make changes in `docker-compose.yml` and `.env` files to use remote or local database

## How to use

1. Open terminal
2. Go to your project folder
3. Run 

    ``` bash
npm start
to start Docker containers with WordPress and MySQL, and local server that will track changes in project files and update browser page (supposed to be used during development)

*or*

``` bash

npm run build-testing

    to get files in `dist` folder ready to deploy to `testing` environment

    *or*

    ``` bash
npm run build-staging
to get files in `dist` folder ready to deploy to `staging` environment

*or*

``` bash

npm run build

    to get files in `dist` folder ready to deploy to production

### Useful tools

#### weinre

weinre is a debugger for web pages, like FireBug (for FireFox) and Web Inspector (for WebKit-based browsers), except it's designed to work remotely, and in particular, to allow debugging of web pages on mobile devices such as a phones.

To enable weinre support (which is enabled in markup index files by default), the following comment should be added to markup:

* in HTML:

    ```html
<!-- weinre -->

  • in Pug:

//- weinre


After that, weinre will be accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

## Workflow

### Local

During developing under local environment all scripts and styles are not minified and source maps are available for them.

By default, project is accessible at [http://localhost:3000](http://localhost:3000) and Browsersync control panel at [http://localhost:3001](http://localhost:3001).

Browsersync works as proxy to WordPress server located at [http://localhost:2999](http://localhost:2999). The difference, why Browsersync is used, is that Browsersync supports live reload and other [features](https://www.browsersync.io).

In addition to that, weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Review

All branches except `dev` and `master` are used to review changes live.

These branches will be built and each one will be available under its own environment with unique address.

For each of them weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Testing

Branch `dev` is used to merge all changes and review them. All developers are responsible to merge their changes to `dev` by themselves.

This branch will be built and available under `testing` environment.

Weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Staging

Branch `master` is used to review changes before deploying to production. It should only contain stable versions that are supposed to be released.

This branch will be built and available under `staging` environment.

Weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group) with debug id `staging`.

### Production

To deploy to production:
1. Create the following [secret variables](https://git.gvia.group/help/ci/variables/README.md#secret-variables):
  * `HOSTING_PROJECT` - project name on hosting server
  * `HOSTING_PROJECT_URL` - project site URL
2. Ask GitLab administrator to assign the project to specific runner that will deploy the project

## Troubleshooting

### Page isn't reloading after source code changes

#### Solution

Check the port in address bar, it should be 3000. Because WordPress URL is [http://localhost:2999](http://localhost:2999), it generates links that starts with and lead to [http://localhost:2999](http://localhost:2999). So just change the port from 2999 to 3000 in your address bar.

### Styles/scripts/other files are not correct/loaded

***Fixed in v1.1***

If you set up the project right, then probably it happens because of [CORS restrictions](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing). In that case the following errors will be printed to browser console:

Access to file at 'http://localhost:2999/...' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access.


#### Solution

If correct/loaded styles/scripts/other files are more important than live reloading, then just go to original WordPress server located at [http://localhost:2999](http://localhost:2999).

### Unable to start project

The most probably that port 2999 is already used. In that case the following error will be printed:

ERROR: for wordpress Cannot start service wordpress: driver failed programming external connectivity on endpoint projectname_wordpress_1 (...container id...): Bind for 0.0.0.0:2999 failed: port is already allocated ERROR: Encountered errors while bringing up the project.


#### Solution

1. Find containers, that use port 2999 of host machine:

    ``` bash
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}" | grep '2999->'
  1. Check the name(s) of container(s), go to their project root and stop them:

docker-compose stop


    *or*

    ``` bash
docker stop <container name(s) or id(s)>
if you don't know to which project that container(s) are related.