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.

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

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

mkaz added the [Type] Documentation label

mkaz requested a review from nosolosw

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

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

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

  
      @@ -148,20 +148,19 @@ Likewise, you do not need to include `node_modules` or any of the above configur
    
        ### 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:

fabiankaegy Sep 19, 2019

Member

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 :)

mkaz Sep 19, 2019

Author Member

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'],

fabiankaegy Sep 19, 2019

Member

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.

gziolo Sep 19, 2019

Member

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

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

mkaz merged commit 5be9acd into master

7 checks passed

7 checks passed

pull-request-automation

Details

Header rules - gutenberg-playground No header rules processed

Details

Pages changed - gutenberg-playground All files already uploaded

Details

Redirect rules - gutenberg-playground No redirect rules processed

Details

Mixed content - gutenberg-playground No mixed content detected

Details

Travis CI - Pull Request Build Passed

Details

netlify/gutenberg-playground/deploy-preview Deploy preview ready!

Details

mkaz deleted the docs/17423-deps branch

jrchamp reviewed

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.

jrchamp Sep 20, 2019

Contributor

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.

jrchamp Sep 20, 2019

Contributor

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:

jrchamp Sep 20, 2019

Contributor

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

  
      @@ -119,7 +119,7 @@ To configure npm to run a script, you use the scripts section in `package.json`
    
        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.

jrchamp Sep 20, 2019

Contributor

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.

jrchamp Sep 20, 2019

Contributor

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

dd32 pushed a commit to dd32/gutenberg that referenced this pull request


        Add dependency management section (WordPress#17489)

5c82c3f

* Add dependency management section

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

Includes various minor rewording updates

* Update documentation to use wp-scripts 5.0.0 format

* Switch variable name, bump scripts to 5.0.0

dd32 pushed a commit to dd32/gutenberg that referenced this pull request


        Wording and other text updates (WordPress#17499)

f1f9245

Updates per @jrchamp review in WordPress#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

You can’t perform that action at this time.