From aa4a18f8f2add27b0c463264611ae9bbc962ff1c Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 14 Mar 2019 09:49:59 -0700 Subject: [PATCH 1/8] WIP --- .../developers/tutorials/javascript/js-build-setup.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index 067e99e5790f2..99bea9b73b051 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -8,10 +8,12 @@ Most browsers can not interpret or run ESNext and JSX syntaxes, so we use a tran There are a few reasons to use ESNext and the extra step. First, it makes for simpler code that is easier to read and write. Using a transformation step allows for tools to optimize the code to work on the widest variety of browsers. Also, by using a build step you can organize your code into smaller modules and files that can be bundled together into a single download. -There are many tools that can perform this transformation or build step, but in this tutorial we will focus on Webpack and Babel. +There are different tools that can perform this transformation or build step, but WordPress uses Webpack and Babel. [Webpack](https://webpack.js.org/) is a pluggable tool that processes JavaScript creating a compiled bundle that runs in a browser. [Babel](https://babeljs.io/) transforms JavaScript from one format to another. You use Babel as a plugin to Webpack to transform both ESNext and JSX to JavaScript. +The @wordpress/scripts package abstracts these libraries away to standardize and simplify development, so you won't need to handle the details for configuring those libraries. + ## Quick Start For a quick start, you can use one of the examples from the [Gutenberg Examples repository](https://github.com/wordpress/gutenberg-examples/). Each one of the `-esnext` directories contain the necessary files for working with ESNext and JSX. @@ -76,9 +78,9 @@ Is this OK? (yes) yes The next step is to install the packages required. You can install packages using the npm command `npm install`. If you pass the `--save-dev` parameter, npm will write the package as a dev dependency in the package.json file. The `--save-exact` parameter instructs npm to save an exact version of a dependency, not a range of valid versions. See [npm install documentation](https://docs.npmjs.com/cli/install) for more details. -Run `npm install --save-dev --save-exact webpack webpack-cli` +Run `npm install --save-dev --save-exact @wordpress/scripts` -After installing, a `node_modules` directory is created with the webpack module and its dependencies. +After installing, a `node_modules` directory is created with the modules and its dependencies. Also, if you look at package.json file it will include a new section: From 830b860a02c6b24e475408d968668e2bc90f8a45 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 14 Mar 2019 10:23:54 -0700 Subject: [PATCH 2/8] Update JS build setup with new wp-scripts commands --- .../tutorials/javascript/js-build-setup.md | 101 +++--------------- 1 file changed, 14 insertions(+), 87 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index 99bea9b73b051..d5f48d88277f4 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -86,68 +86,19 @@ Also, if you look at package.json file it will include a new section: ```json "dependencies": { - "webpack": "4.29.0" + "@wordpress/scripts": "3.1.0" } ``` ## Webpack & Babel -Next, we will configure webpack to process the `block.js` file and run babel to transform the JSX within it. +The @wordpress/scripts package handles the default configuration for Webpack and Babel. You need to add the following packages -Create the file `webpack.config.js` - -```js -// sets mode webpack runs under -const NODE_ENV = process.env.NODE_ENV || 'development'; - -module.exports = { - mode: NODE_ENV, - - // entry is the source script - entry: './block.js', - - // output is where to write the built file - output: { - path: __dirname, - filename: 'block.build.js', - }, - module: { - // the list of rules used to process files - // this looks for .js files, exclude files - // in node_modules directory, and uses the - // babel-loader to process - rules: [ - { - test: /.js$/, - exclude: /node_modules/, - loader: 'babel-loader', - }, - ], - }, -}; ``` - -Next, you need to install babel, the webpack loader, and the JSX plugin using: - -`npm install --save-dev --save-exact babel-loader @babel/core @babel/plugin-transform-react-jsx` - -You configure babel by creating a `.babelrc` file: - -```json -{ - "plugins": [ - [ "@babel/plugin-transform-react-jsx", { - "pragma": "wp.element.createElement" - } ] - ] -} +npm install --save-dev webpack webpack-cli @wordpress/babel-preset-default babel-plugin-transform-react-jsx ``` -This pragma setting instructs Babel that any JSX syntax such as `` should be transformed into `wp.element.createElement( Hello )`. The name of the setting (`transform-react-jsx`) is derived from the fact that it overrides the default assumption to transform to `React.createElement( Hello )`. - -With both configs in place, you can now run webpack. - -First you need a basic block.js to build. Create `block.js` with the following content: +The scripts package expects the source file to compile to be found at `src/index.js` and will output to `build/index.js`. So create a basic block to build. Create a file at `src/index.js` with the following content: ```js const { registerBlockType } = wp.blocks; @@ -169,71 +120,47 @@ To configure npm to run a script, you use the scripts section in `package.json` ```json "scripts": { - "build": "webpack" + "build": "wp-scripts build" }, ``` You can then run the build using: `npm run build`. -After the build finishes, you will see the built file created at `block.build.js`. +After the build finishes, you will see the built file created at `build/index.js`. ## Finishing Touches ### Development Mode -The basics are in place to build. You might have noticed the webpack.config.js sets a default mode of "development". Webpack can also run in a "production" mode, which shrinks the code down so it downloads faster, but makes it difficult to read. +The **build** command in @wordpress/scripts runs in a production mode which shrinks the code down so it downloads faster, but makes it difficult to read. You can use the **start** command which runs a development mode that does not shrink the code, and additionally continues a running process to watch the source file for more changes and rebuilt as you develop. -The mode is setup so it can be configured using environment variables, which can be added in the scripts section of `package.json`. +The start command can be added to the same scripts section of `package.json`. ```json "scripts": { - "dev": "webpack --watch", - "build": "cross-env NODE_ENV=production webpack" + "start": "wp-scripts start", + "build": "wp-scripts build" }, ``` -This sets the environment variables, but different environments handle these settings in different ways. Using the `cross-env` helper module can help to handle this. Be sure to install the `cross-env` package using `npm install --save-dev --save-exact cross-env`. - -Additionally, webpack has a `--watch` flag that will keep the process running, watching for any changes to the `block.js` file and re-building as changes occur. This is useful during development, when you might have a lot of changes in progress. - -You can start the watcher by running `npm run dev` in a terminal. You can then edit away in your text editor; after each save, webpack will automatically build. You can then use the familiar edit/save/reload development process. +Now, when you run `npm run start` a watcher will run in the terminal. You can then edit away in your text editor; after each save, it will automatically build. You can then use the familiar edit/save/reload development process. **Note:** keep an eye on your terminal for any errors. If you make a typo or syntax error, the build will fail and the error will be in the terminal. -### Babel Browser Targeting - -Babel has the ability to build JavaScript using rules that target certain browsers and versions. By setting a reasonable set of modern browsers, Babel can optimize the JavaScript it generates. - -WordPress has a preset default you can use to target the minimum supported browsers by WordPress. - -Install the module using: `npm install --save-dev --save-exact @wordpress/babel-preset-default` - -You then update `.babelrc` by adding a "presets" section: - -``` -{ - "presets": [ "@wordpress/babel-preset-default" ], - "plugins": [ - [ "@babel/plugin-transform-react-jsx", { - "pragma": "wp.element.createElement" - } ] - ] -} -``` ### Source Control Because a typical `node_modules` folder will contain thousands of files that change with every software update, you should exclude `node_modules/` from your source control. If you ever start from a fresh clone, simply run `npm install` in the same folder your `package.json` is located to pull your required packages. -Likewise, you do not need to include `node_modules` or any of the above configuration files in your plugin because they will be bundled inside the file that webpack builds. **Be sure to enqueue the `block.build.js` file** in your plugin PHP. This is the only JavaScript file needed for your block to run. +Likewise, you do not need to include `node_modules` or any of the above configuration files in your plugin because they will be bundled inside the file that webpack builds. **Be sure to enqueue the `build/index.js` file** in your plugin PHP. This is the only JavaScript file needed for your block to run. ## Summary -Yes, the initial setup is rather tedious, and there are a number of different tools and configs to learn. However, as the quick start alluded to, copying an existing config is the typical way most people start. +Yes, the initial setup is a bit more involved, but once in place adds additional features which are usually worth the trade off. With a setup in place, the standard workflow is: - Install dependencies: `npm install` -- Start development builds: `npm run dev` +- Start development builds: `npm run start` - Develop. Test. Repeat. - Create production build: `npm run build` From 02f69099e05b68e75683a41522026e91482729b6 Mon Sep 17 00:00:00 2001 From: Chris Van Patten Date: Thu, 14 Mar 2019 10:46:52 -0700 Subject: [PATCH 3/8] Apply suggestions from code review Thanks ! Co-Authored-By: mkaz --- .../tutorials/javascript/js-build-setup.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index d5f48d88277f4..8fa703917da41 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -12,7 +12,7 @@ There are different tools that can perform this transformation or build step, bu [Webpack](https://webpack.js.org/) is a pluggable tool that processes JavaScript creating a compiled bundle that runs in a browser. [Babel](https://babeljs.io/) transforms JavaScript from one format to another. You use Babel as a plugin to Webpack to transform both ESNext and JSX to JavaScript. -The @wordpress/scripts package abstracts these libraries away to standardize and simplify development, so you won't need to handle the details for configuring those libraries. +The `@wordpress/scripts` package abstracts these libraries away to standardize and simplify development, so you won't need to handle the details for configuring those libraries. ## Quick Start @@ -80,7 +80,7 @@ The next step is to install the packages required. You can install packages usin Run `npm install --save-dev --save-exact @wordpress/scripts` -After installing, a `node_modules` directory is created with the modules and its dependencies. +After installing, a `node_modules` directory is created with the modules and their dependencies. Also, if you look at package.json file it will include a new section: @@ -92,13 +92,15 @@ Also, if you look at package.json file it will include a new section: ## Webpack & Babel -The @wordpress/scripts package handles the default configuration for Webpack and Babel. You need to add the following packages +The `@wordpress/scripts` package handles the default configuration for Webpack and Babel. You need to add the following packages: ``` npm install --save-dev webpack webpack-cli @wordpress/babel-preset-default babel-plugin-transform-react-jsx ``` -The scripts package expects the source file to compile to be found at `src/index.js` and will output to `build/index.js`. So create a basic block to build. Create a file at `src/index.js` with the following content: +The scripts package expects the source file to compile to be found at `src/index.js`, and will save the compiled output to `build/index.js`. + +With that in mind, let's set up a basic block. Create a file at `src/index.js` with the following content: ```js const { registerBlockType } = wp.blocks; @@ -132,9 +134,9 @@ After the build finishes, you will see the built file created at `build/index.js ### Development Mode -The **build** command in @wordpress/scripts runs in a production mode which shrinks the code down so it downloads faster, but makes it difficult to read. You can use the **start** command which runs a development mode that does not shrink the code, and additionally continues a running process to watch the source file for more changes and rebuilt as you develop. +The **build** command in `@wordpress/scripts` runs in a "production" mode. This shrinks the code down so it downloads faster, but makes it difficult to read in the process. You can use the **start** command which runs a development mode that does not shrink the code, and additionally continues a running process to watch the source file for more changes and rebuild as you develop. -The start command can be added to the same scripts section of `package.json`. +The start command can be added to the same scripts section of `package.json`: ```json "scripts": { @@ -156,7 +158,7 @@ Likewise, you do not need to include `node_modules` or any of the above configur ## Summary -Yes, the initial setup is a bit more involved, but once in place adds additional features which are usually worth the trade off. +Yes, the initial setup is a bit more involved, but the additional features and benefits are usually worth the trade off in setup time. With a setup in place, the standard workflow is: From c3de1616e3ac5b9193452ae942e1f99a7014043d Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 14 Mar 2019 12:02:05 -0700 Subject: [PATCH 4/8] Remove webpack, babel dependencies --- .../developers/tutorials/javascript/js-build-setup.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index 8fa703917da41..c6459abc68cf1 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -92,13 +92,7 @@ Also, if you look at package.json file it will include a new section: ## Webpack & Babel -The `@wordpress/scripts` package handles the default configuration for Webpack and Babel. You need to add the following packages: - -``` -npm install --save-dev webpack webpack-cli @wordpress/babel-preset-default babel-plugin-transform-react-jsx -``` - -The scripts package expects the source file to compile to be found at `src/index.js`, and will save the compiled output to `build/index.js`. +The `@wordpress/scripts` package handles the dependencies and default configuration for Webpack and Babel. The scripts package expects the source file to compile to be found at `src/index.js`, and will save the compiled output to `build/index.js`. With that in mind, let's set up a basic block. Create a file at `src/index.js` with the following content: From 9a282b7bae4efb67774469a1fe44083332907145 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 15 Mar 2019 10:06:36 +0100 Subject: [PATCH 5/8] Use output from build as entry point --- .../developers/tutorials/javascript/js-build-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index c6459abc68cf1..d752d253d92bd 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -50,7 +50,7 @@ npm init package name: (myguten-block) myguten-block version: (1.0.0) description: Test block -entry point: (index.js) block.js +entry point: (index.js) build/index.js test command: git repository: keywords: From 8f5f01aee384b331590b972d4f14e25b6edc2546 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 15 Mar 2019 10:07:02 +0100 Subject: [PATCH 6/8] cd into the new folder before executing npm commands --- .../developers/tutorials/javascript/js-build-setup.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index d752d253d92bd..50a59733d8a4f 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -40,6 +40,7 @@ To start a new node project, first create a directory to work in. ``` mkdir myguten-block +cd myguten-block ``` You create a new package.json running `npm init` in your terminal. This will walk you through creating your package.json file: From 6b95f870d3485162c3902d50a65471c0347b8eec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 15 Mar 2019 10:14:19 +0100 Subject: [PATCH 7/8] Use arrow functions for effect --- .../developers/tutorials/javascript/js-build-setup.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index 50a59733d8a4f..c25d4bc9d3dbd 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -104,12 +104,8 @@ registerBlockType( 'myguten/test-block', { title: 'Basic Example', icon: 'smiley', category: 'layout', - edit() { - return
Hola, mundo!
; - }, - save() { - return
Hola, mundo!
; - }, + edit: () =>
Hola, mundo!
, + save: () =>
Hola, mundo!
, } ); ``` From d051c6d724e043a7a22879339b8820a390bfa157 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Fri, 15 Mar 2019 11:07:01 -0700 Subject: [PATCH 8/8] Update docs/designers-developers/developers/tutorials/javascript/js-build-setup.md Co-Authored-By: mkaz --- .../developers/tutorials/javascript/js-build-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md index c25d4bc9d3dbd..ebd65dc6a232d 100644 --- a/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md +++ b/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md @@ -12,7 +12,7 @@ There are different tools that can perform this transformation or build step, bu [Webpack](https://webpack.js.org/) is a pluggable tool that processes JavaScript creating a compiled bundle that runs in a browser. [Babel](https://babeljs.io/) transforms JavaScript from one format to another. You use Babel as a plugin to Webpack to transform both ESNext and JSX to JavaScript. -The `@wordpress/scripts` package abstracts these libraries away to standardize and simplify development, so you won't need to handle the details for configuring those libraries. +The [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts) package abstracts these libraries away to standardize and simplify development, so you won't need to handle the details for configuring those libraries. ## Quick Start