You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
BeAPI FrontEnd Framework (BFF) is a Front-end WordPress theme friendly boilerplate to help you to build your own WordPress theme with modern tools and a better productivity.
**Be API FrontEnd Framework** (BFF) is a friendly Front-end WordPress theme boilerplate to help you to start your own WordPress theme with modern tools.
20
11
21
-
## Requirements
12
+
## ⚒️ Main tools
13
+
*[Webpack 5](https://webpack.js.org/) JS, CSS and assets are built with Webpack.
14
+
*[Babel](https://babeljs.io/) for ES6 browser support.
15
+
*[Eslint](https://eslint.org/) for JS code style.
16
+
*[Stylelint](https://stylelint.io/) for CSS code style.
17
+
*[CSSNano](https://cssnano.co/) for CSS optimization
18
+
*[PostCSS Preset Env](https://github.com/csstools/postcss-preset-env) for modern CSS properties compatibility.
19
+
*[PostCSS PX to REM](https://github.com/cuth/postcss-pxtorem) to automatically convert px units to rem.
20
+
*[PostCSS Sort Media Queries](https://github.com/solversgroup/postcss-sort-media-queries) to combine multiple similar medie queries declarations.
21
+
*[SVGO](svgo-loader) for SVG optimization.
22
+
*[Image Webpack Loader](image-webpack-loader) for images optimization.
23
+
*[Browser Sync](https://browsersync.io/) to test your project on different devices.
24
+
25
+
26
+
27
+
## 🔴 Requirements
22
28
23
29
### Composer
24
30
You need composer to autoload all your classes from the inc folder.
25
31
26
32
Use the `beapi/composer-scaffold-theme` package that add it automatically to the composer.json file.
27
33
You can add it yourself like this :
28
-
34
+
29
35
```composer.json
30
36
"autoload": {
31
37
"psr-4": {
@@ -34,16 +40,16 @@ You can add it yourself like this :
34
40
}
35
41
```
36
42
37
-
## Autoload
43
+
###Autoload
38
44
The autoload is based on psr-4 and handled by composer.
39
45
40
-
### Node 8
46
+
### Node 12+
41
47
42
-
You need a minimum of Node 8.
48
+
You need a minimum of Node 12. Version 14 is recommended.
43
49
44
50
### Advanced Responsive Images
45
51
46
-
You need to work in a wordpress environment in order to make the BFF work with webpack for local dev. To do that you need to install [Advanced Responsive Images](https://github.com/asadowski10/advanced-responsive-images) in your plugin folder.
52
+
You need to work in a WordPress environment in order to make the BFF work with webpack for local dev. To do that you need to install [Advanced Responsive Images](https://github.com/asadowski10/advanced-responsive-images) in your `plugins` folder.
47
53
48
54
## Installation
49
55
@@ -72,218 +78,46 @@ Then install node dependencies with NPM or Yarn.
72
78
$ npm install
73
79
```
74
80
75
-
## Configuration
81
+
## ⚙️ Configuration
82
+
83
+
The configurations files are in `config` directory.
76
84
### Webpack
77
-
You can edit Webpack configuration with `webpack.config.js` file and settings by editing `webpack.settings.js`.
85
+
You can find the common Webpack settings file in `webpack.common.js`. For development mode purpose, you can edit `webpack.dev.js` file and for production mode, you can edit `webpack.prod.js`.
86
+
You also have the loaders in `loaders.js` file and Webpack's plugin in `plugins.js` file.
78
87
79
88
### Babel
80
89
You can find a `.babelrc` file to modify Babel configuration.
81
90
82
91
### Eslint
83
-
You can find a `.eslintrc.js` file to modify Eslint configuration and ignore files in `.eslintignore`.
92
+
You can find a `.eslintrc` file to modify Eslint configuration.
84
93
85
-
## How to use BFF ?
94
+
## 🚀 How to use BFF ?
86
95
After installing dependencies, you can run some commands which are explained below.
87
96
88
-
### Local Server with Browser Sync
89
-
You probably need to add this following line in your `hosts` file.
90
-
91
-
```
92
-
::1 localhost
93
-
```
94
-
95
-
and run a first time the following command to generate required distributions files to run the server properly.
96
-
```
97
-
$ npm run build:dev
98
-
```
99
-
100
-
Then, you can run a "Petit PHP" local server with Browser Sync by running :
101
-
```bash
102
-
$ npm start
103
-
```
104
-
105
-
### Watching files for development purpose
106
-
If you don't need a local server you just can compile AND watch styles and scripts (with sourcemap) by using :
107
-
108
-
```bash
109
-
$ npm run watch
110
-
```
97
+
### Start with Browser Sync
111
98
112
-
### Development build
113
-
If you want to build styles and scripts (with sourcemap) by using :
99
+
BFF is configured to work with [lando](https://lando.dev/). If you have a `.lando.yml` file in your project's root, set the path to your file in the `browsersync.config.js` file.
114
100
115
-
```bash
116
-
$ npm run build:dev
101
+
```js
102
+
let fileContents =fs.readFileSync('../../../../.lando.yml', 'utf8')
117
103
```
104
+
Then, run the following command from the theme :
118
105
119
-
### Production build
120
-
For production purpose, you can compile all of your assets by using :
121
106
122
107
```bash
123
-
$ npm run build:prod
108
+
$ npm start
124
109
```
125
-
126
-
If you want to deliver assets for both developpement and production, run :
110
+
BrowserSync will proxy your lando'server based on the name defined in your `.lando.yml`.
111
+
### Build
127
112
128
113
```bash
129
114
$ npm run build
130
115
```
131
116
132
-
### Bump WordPress theme version
133
-
You can change your WordPress theme's version by using :
134
-
135
-
```bash
136
-
$ npm run bump [-t |-type] [patch | minor | major]
137
-
```
138
-
139
-
It will change the version of your theme filled in the `style.css` file in the theme's root.
140
-
There are 3 kinds of update available : patch, minor or major.
117
+
### Bundle report
141
118
142
-
In the case of a multiple themes of a Wordpress project, you can use the previous task in any themes in one command with a bash script. To use the command, you have to move the `build.sh` file based in your WordPress theme's root to your WordPress project's root and go to the Wordpress root path with your Terminal software.
119
+
You can launch a bundle report with the following command :
143
120
144
121
```bash
145
-
$ mv build.sh ../../../
146
-
$ cd ../../../
147
-
```
148
-
149
-
By the way, you can specify the type of bump wanted.
150
-
151
-
```bash
152
-
$ sh build.sh [-t |-type] [patch | minor | major]
153
-
```
154
-
155
-
### Assets
156
-
#### Favicons
157
-
158
-
Generate appicons and favicons from the sources files in src/img/favicons/ by using :
159
-
160
-
```bash
161
-
$ npm run favicon
162
-
```
163
-
164
-
#### SVG Icons
165
-
Generate SVG sprite from the icons files in src/img/icons/ by using :
166
-
167
-
```bash
168
-
$ npm run icon
169
-
```
170
-
171
-
Generate JSON image sizes and locations (more details in the [Responsive images section](#responsive-images)) by using :
172
-
173
-
```bash
174
-
# you can add csv as argument to generate a CSV file of image locations
175
-
$ npm run image [csv]
176
-
```
177
-
178
-
## Composer JS
179
-
180
-
In order to keep a lightweight stack, you can add extra components that are used most of the time in Web dev by using :
181
-
182
-
```bash
183
-
$ npm run composerjs
184
-
```
185
-
186
-
You can find the list of SCSS and JS components to use [here](https://github.com/BeAPI/beapi-frontend-framework/blob/master/composerjs).
187
-
188
-
## Responsive images
189
-
190
-
WordPress native thumbnails are not enough for us. We want to build images :
191
-
* That can have differents art direction between differents viewports
192
-
* That can be displayed in the good resolution
193
-
* That can be lazyloaded, but still accessible if no Javascript
<imgsrc="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="class="lazyload"alt="image with artdirection"/>
212
-
</picture>
213
-
```
214
-
215
-
So with the [Advanced Responsive Images](https://github.com/asadowski10/advanced-responsive-images) plugin we can manage a `picture` tag with different file configuration.
216
-
217
-
* provide a 2x img with "x" descriptor. perfect for thumbnails. ( srcset="my_image, my_image-HD 2x" )
218
-
* provide a range of image depend on viewport with "w" descriptor. ( srcset="my_image-mobile 480w, my_image-tablet 768w, etc." )
219
-
220
-
You have to build your picture template in `src/conf-img/tpl`. `default-picture.tpl` is the main `<picture>` container. In this tpl we can see the reference for the sources we want, for example in `entry-img-01.tpl` we want a square image under 1024px viewport, displayed in normal or 2x resolution, for bigger screen a landscape image:
Then run the following command to generate your JSON image locations and sizes :
226
-
```
227
-
$ npm run image
228
-
```
229
-
230
-
Example of *src/conf-img/images-sizes.json* :
231
-
```json
232
-
"img-100-100":
233
-
{
234
-
"width":"100",
235
-
"height":"100",
236
-
"crop":true
237
-
}
238
-
```
239
-
Example of *src/conf-img/images-locations.json* :
240
-
241
-
```json
242
-
"entry-img-01": [
243
-
{
244
-
"srcsets": [
245
-
{
246
-
"size": "img-100-100"
247
-
},
248
-
{
249
-
"size": "img-200-200"
250
-
},
251
-
{
252
-
"size": "img-300-200"
253
-
},
254
-
{
255
-
"size": "img-600-400"
256
-
}
257
-
],
258
-
"default_img": "default-300-200.jpg",
259
-
"img_base": "img-300-200"
260
-
}
261
-
]
262
-
```
263
-
264
-
`default_img` is used for default image if no image are provoded in WordPress Admin. `img_base` is used as fallback for older browser.
265
-
266
-
You can use this [Sketch extension](https://github.com/Nkzq/advanced-responsive-images-default) to generate default image according to your *images-locations.json* file. There is a sketch file provided in the *src/img/default* folder.
We add Lazyload support too! We use [Lazysize](https://github.com/aFarkas/lazysizes) in addition to picturefill in order to provide responsive image served as fast as possible.
278
-
279
-
If you don't want this feature you still can set BEA_LAZYSIZE to false in /functions/class-bea-images.php. it will turn the markup to basic img tag with srcset.
280
-
281
-
Lazysize is also used for displaying background image in different sizes for differents viewports. Look at the Lazysize bgset documentation and the `page__header` or `hero` pattern.
282
-
283
-
# Who ?
284
-
285
-
Created by [Be API](https://beapi.fr), the French WordPress leader agency since 2009. Based in Paris, we are more than 30 people and always [hiring](https://beapi.workable.com) some fun and talented guys. So we will be pleased to work with you.
286
-
287
-
This plugin is only maintained, which means we do not guarantee some free support. Consider reporting an [issue](#issues--features-request--proposal) and be patient.
288
-
289
-
If you really like what we do or want to thank us for our quick work, feel free to [donate](https://www.paypal.me/BeAPI) as much as you want / can, even 1€ is a great gift for buying coffee :)
0 commit comments