New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add dependency management section #17489

Merged

mkaz merged 3 commits into master from docs/17423-deps

Sep 20, 2019

Member

mkaz commented Sep 19, 2019 •

edited

Description

Adds new section Dependency Management to the JavaScript Tutorial that explains how to use index.asset.php from wp-scripts 5.0.0

Bonus: while reading through the document I updated various rewording and simplified a few bits.

Gutenberg Examples repo updated in:
WordPress/gutenberg-examples#89

Fixes #17423

How has this been tested?

Follow example instructions and confirm dependency loading works as described.

Types of changes

Documentation update, view live on branch here


          Add dependency management section

89cc02f

Adds new section on how to use index.deps.json for automatic dependency
management

Includes various minor rewording updates

mkaz requested review from ajitbohra, chrisvanpatten and youknowriad as code owners

September 19, 2019 19:14

mkaz added the [Type] Developer Documentation label

mkaz requested a review from oandregal

September 19, 2019 19:15

mkaz self-assigned this

Member

fabiankaegy commented Sep 19, 2019

Whats the plan here because it looks from the outside that the .deps.json files are already replaced by the new .asset.php files? 😃

Member Author

mkaz commented Sep 19, 2019

@fabiankaegy good question, I haven't seen .asset.php yet. My recent use of wp-scripts still generates the index.deps.json file. Do you have a link that shows the new format?

Member Author

mkaz commented Sep 19, 2019

@fabiankaegy I found it #17298 looks like it is just 3 days old, which is why I hadn't seen it before.

Guess it took too long to get around to documenting .deps.json and it got replaced.

Member

fabiankaegy commented Sep 19, 2019

@mkaz Yeah I felt the same way 😂 just got used to the .json files and then started a new project today and was thrown by the .php files. And was not able to find any example of how to use it 😂

but a basic include saved in a variable and then accessing the [dependencies] or [version]


          Update documentation to use wp-scripts 5.0.0 format

0ee76d3

mkaz requested a review from gziolo

September 19, 2019 20:40

Member Author

mkaz commented Sep 19, 2019

@fabiankaegy I updated the docs with the index.asset.php usage and the sister PR over in WordPress/gutenberg-examples#89

fabiankaegy reviewed

View reviewed changes

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

               ### Dependency Management
-              The build step also produces a `index.deps.json` file that contains a JSON array of the wp packages required for your block. For our simple example above would be `["wp-blocks","wp-polyfill"]`
+              Using wp-scripts ver 5.0.0+ build step will also produce a `index.asset.php` file that contains an array of dependencies and version number for your block. For our simple example above is something like:

Member

fabiankaegy Sep 19, 2019

It generates this .asset.php file for each of the entry points. so if you add your cutsom entry points they will get this file swell :)

Member Author

mkaz Sep 19, 2019

That is true, but our JS tutorial is intended for beginners and does not include any description on how one would configure multiple entry points. It is more of an advanced topic better left for package documentation not this tutorial.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md Outdated

               wp_register_script(
               	'myguten-block',
               	plugins_url( 'build/index.js', __FILE__ ),
-              	$dependencies
+              	$depver['dependencies'],

Member

fabiankaegy Sep 19, 2019

One think that I found useful was that its just an array and that you can use functions like array_merge() to add your own custom dependencies to it if you need that.

Member

gziolo Sep 19, 2019

Yes, we do it in Gutenberg and this is going to be added to WP core now we can include static PHP file. This was also the reason why we changed the format. We plan to add more details to the file to eventually make it possible to pass only the name of the file when registering an asset. The rest would be handy behind the scenes 🔮

gziolo reviewed

View reviewed changes

Member

gziolo left a comment

Nice addition, I left some minor comments and further explanation about the asset file.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md Outdated Show resolved Hide resolved

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md Outdated Show resolved Hide resolved


          Switch variable name, bump scripts to 5.0.0

90cb967

gziolo approved these changes

View reviewed changes

mkaz merged commit 5be9acd into master

mkaz deleted the docs/17423-deps branch

September 20, 2019 13:22

jrchamp reviewed

View reviewed changes

Contributor

jrchamp left a comment

I know it's too late now, but I just saw this.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

    
            @@ -1,18 +1,18 @@
          
              # JavaScript Build Setup

              This page covers how to set up your development environment to use the ESNext and [JSX](https://reactjs.org/docs/introducing-jsx.html) syntaxes. ESNext is JavaScript code written using features that are only available in a specification greater than ECMAScript 5 (ES5 for short). JSX is a custom syntax extension to JavaScript which helps you to describe what the UI should look like.

              This page covers how to set up your development environment to use the ESNext and [JSX](https://reactjs.org/docs/introducing-jsx.html) syntaxes. ESNext is JavaScript code written using features that are only available in a specification greater than ECMAScript 5 (ES5 for short). JSX is a custom syntax extension to JavaScript that allows you write JavaScript in a more familiar tag syntax.

Contributor

jrchamp Sep 20, 2019

Suggested change

      
            This page covers how to set up your development environment to use the ESNext and [JSX](https://reactjs.org/docs/introducing-jsx.html) syntaxes. ESNext is JavaScript code written using features that are only available in a specification greater than ECMAScript 5 (ES5 for short). JSX is a custom syntax extension to JavaScript that allows you write JavaScript in a more familiar tag syntax.
          
            This page covers how to set up your development environment to use the ESNext and [JSX](https://reactjs.org/docs/introducing-jsx.html) syntaxes. ESNext is JavaScript code written using features that are only available in a specification greater than ECMAScript 5 (ES5 for short). JSX is a custom syntax extension to JavaScript that allows you to write JavaScript in a more familiar tag syntax.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

               Most browsers can not interpret or run ESNext and JSX syntaxes, so we use a transformation step to convert these syntaxes to code that browsers can understand.
               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 different tools that can perform this transformation or build step, but WordPress uses webpack and Babel.
+              There are different tools that can perform this transformation or build step, WordPress uses webpack and Babel.

Contributor

jrchamp Sep 20, 2019

Suggested change

      
            There are different tools that can perform this transformation or build step, WordPress uses webpack and Babel.
          
            There are different tools that can perform this transformation or build step; WordPress uses webpack and Babel.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

    
            @@ -22,15 +22,15 @@ For a quick start, you can use one of the examples from the [Gutenberg Examples
          
              Both webpack and Babel are tools written in JavaScript and run using [Node.js](https://nodejs.org/) (node). Node.js is a runtime environment for JavaScript outside of a browser. Simply put, node allows you to run JavaScript code on the command-line.

              First, you need to set up node for your development environment. The steps required change depending on your operating system, but if you have a package manager installed, setup can be as straightforward as:

              First, you need to set up node for your development environment. The steps required depend on your operating system, if you have a package manager installed, setup can be as straightforward as:

Contributor

jrchamp Sep 20, 2019

Suggested change

      
            First, you need to set up node for your development environment. The steps required depend on your operating system, if you have a package manager installed, setup can be as straightforward as:
          
            First, you need to set up Node.js for your development environment. The steps required depend on your operating system. If you have a package manager installed, setup can be as straightforward as:

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

               You can then run the build using: `npm run build`.
-              After the build finishes, you will see the built file created at `build/index.js`.
+              After the build finishes, you will see the built file created at `build/index.js`. Enqueue this file in the admin screen as shown in Step 2, and the block will load in the editor.

Contributor

jrchamp Sep 20, 2019

There is nothing labeled "Step 2". It would be best to reference something that exists/can be found on the current page.

docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

+              Using wp-scripts ver 5.0.0+ build step will also produce a `index.asset.php` file that contains an array of dependencies and version number for your block. For our simple example above is something like:
+              `array('dependencies' => array('wp-element', 'wp-polyfill'), 'version' => 'fc93c4a9675c108725227db345898bcc');`
+              Here is how to use this asset file to automatically set the dependency list for enqueing the script. This prevents having to manually update the dependencies, it will be created based on the package imports used within your block.

Contributor

jrchamp Sep 20, 2019

enqueuing or enqueueing; not enqueing. My browser only likes the first one.

mkaz added a commit that referenced this pull request


          Wording and other text updates

b3ed038

Updates per @jrchamp review in #17489

mkaz mentioned this pull request

Wording and other text updates for JS tutorial #17499

Merged

Member Author

mkaz commented Sep 20, 2019 •

edited

Thanks @jrchamp for the review. I created this PR for addressing your suggestions.
#17499

mkaz added a commit that referenced this pull request


          Wording and other text updates (#17499)

b183464

Updates per @jrchamp review in #17489

youknowriad added this to the Gutenberg 6.6 milestone

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

jrchamp jrchamp left review comments

fabiankaegy fabiankaegy left review comments

gziolo gziolo approved these changes

ajitbohra Awaiting requested review from ajitbohra

chrisvanpatten Awaiting requested review from chrisvanpatten

youknowriad Awaiting requested review from youknowriad

oandregal Awaiting requested review from oandregal