[BUG] package.json files section wrong #230

Closed Ryvix closed 1 year ago

Hello,

It's been awhile and I found myself back testing this wonderful looking software again. I completely forgot I posted here (#202) before. I was trying to do the same thing again and found myself right back there again reading my own comment. So I thought I would post an update in case it helps anyone.

First though, since that other issue is actually about requesting a recipe for GitHub release I should note that I personally am not looking to completely submit most of my plugins to wordpress.org or to GitHub, although that might be neat too, and I did notice you have some GitHub Actions and even a GitLab CI, I just want to try and make a zip file of it automatically so I can do whatever I want with it. That seemed to be what people commenting there were also trying to do. Although being able to release to wordpress.org SVN or to GitHub automatically might be pretty sweet too but I would understand if you think that is outside the scope of WPBP.

In fact I've written a system to dynamically output the JSON to respond to the yahnis-elsts/plugin-update-checker library that WPBP uses and that allows me to essentially run a plugin update repository myself where I put the zip files for offering updates to wherever the plugin is installed. So I really just have to get that zip file.

I just tested the WPBP generator and had to modify it a bit to make it work for me. The GitHub archive URLs seemed wrong so I changed them to the right ones. I also think the files section within the package.json file is wrong and include a fix for that below. Then once I did those things I am actually able to generate the zip file! Woohoo! This is getting exciting now.

The scripts section in the package.json appears to run various wp-scripts commands including a plugin-zip command which I think is all part of an official WP plugin package which has more documentation here:

https://github.com/WordPress/gutenberg/blob/trunk/packages/scripts/README.md

https://www.npmjs.com/package/@wordpress/scripts

However, since I wasn't familiar enough with the WPBP codebase still I didn't know exactly which files and folders to include in the zip file still or how to make the plugin-zip command include them. Mainly because it currently seems like it doesn't do it properly, it doesn't include all the files and folders.

I noticed this section in the package.json:

    "files": {
        "0": "ajax/*",
        "1": "backend/*",
        "3": "cli/*",
        "4": "engine/*",
        "5": "frontend/*",
        "6": "functions/*",
        "7": "integrations/*",
        "8": "internals/*",
        "9": "rest/*",
        "10": "templates/*"
    },

However it is highlighted in my IDE saying: Incompatible types. Required: array. Actual: object.

According to the @wordpress/scripts documentation it says it should be in this format:

{
    "files": [ "dir" ]
}

So I updated that section to be like this:

    "files": [
        "ajax/*",
        "assets/*",
        "backend/*",
        "cli/*",
        "engine/*",
        "frontend/*",
        "functions/*",
        "integrations/*",
        "internals/*",
        "languages/*",
        "rest/*",
        "templates/*",
        "vendor/*",
        "index.php",
        "LICENSE.txt",
        "plugin-name.php",
        "README.txt",
        "uninstall.php"
    ],

Of course you have to update the plugin-name to your plugin file and add any extra files or folders.

I also realized I had to add some missing files and folders that were in there by default that have to be included in the zip for the plugin to function properly.

Once you do these things you can run npm run plugin-zip and it will make a zip file and update it if you run it again.

I'm not sure if it should exclude the assets/src folder. Although I noticed the assets/src/block/block.json file is used by the internals/Block.php register_block function. It's probably fine to keep the src folder but it might add some extra size to the final zip is all.

There is possibly some way to ignore files but I couldn't get it to work. If they are added to .gitignore or using .npmignore files they are supposed to be ignored: https://www.npmjs.com/package/npm-packlist#user-content-interaction-between-packagejson-and-npmignore-rules

I think I read somewhere that the files section overrides those. I'm not sure if there is a way around that. I would have to do more digging but I'm out of time for now.

After testing, I can confirm that it does NOT ignore the vendor and build folders which are in the .gitignore. They are included into the zip after I changed the files section as shown above. So I suppose that's good. But if we want to ignore files what do we do?

Note that we can also add a .prettierignore file to make it not format them automatically. I wonder if this works as well.

As a side note, I think maybe we still struggle to use this boilerplate/framework possibly due to a lack of documentation and experience in using the libraries and tools it includes. While there is some documentation it's hard to figure out for someone who isn't familiar with it all and how it all ties together. A step-by-step tutorial of an entire process from start to finish could be very valuable. If there is one I must have missed it. The closest I could find is maybe on the wiki and it's all good.

I really appreciate all the work put into this! Massive effort. Love it!

Hi, thanks for the long comment!

So the issue you saw in the package.json is generated by the generator https://github.com/wpBP/generator. I tried in the past to understand what is happening and why probably it is something on the json_encode stuff on saving the updated json.

About the commands I am not using them but they were added by @erikyo in the project so maybe he can help check those.

About the libraries let me know where is needed more documentation (also on https://wpbp.github.io/) as this is after all a solo project, so any feedback is important to address the various issues.
A step by step tutorial it is not so simple considering all the libraries included so probably make sense to write some tutorial for the various uses cases like "I don't want to publish my plugin on wp.org" and so on.

That makes sense. I know this is probably not complete but how about something like this page:

WordPress Plugin Boilerplate Powered

WordPress Plugin Boilerplate but Powered with examples and a generator!

Website | Wiki | GitHub

Generator

WPBP/generator
Code Generator for the WPBP

The final usage ultimately depends on what you edit in the wpbp.json and composer.json files, and of course any other changes you've made. You should be able to run the commands and edit the files mentioned below to get started. Read all these links and edit the code however you like using the libraries, snippets, and tools listed below.

:warning: These steps may be incomplete and need expanded upon and testing. For example, you may also want to run tests, Codeception, etc.

Generate a new wpbp.json file in the current folder: wpbp-generator --json
Edit the wpbp.json to your liking by removing what you don't want.
Downloads WPBP and extracts it to a new folder and removes the parts you don't want: wpbp-generator
Your new plugin folder is created as a subfolder in the current working directory.
This is where I had to patch the package.json file to change the files object to a one dimensional array and add the correct files and folders. Patched version is shown down below. Be sure to update your plugin-name.php to your plugin file.
Change into your plugin folder: cd your-plugin-folder
Edit composer.json and change versions or packages to your liking.
Install fresh with dev files: composer install
Optimize composer classes: composer dumpautoload -o
Install node packages: npm install
Zip plugin files: npm run plugin-zip

:information_source: Optional: Update composer with no dev files: composer --no-dev update

:information_source: You can verify files to zip by running this command: npm pack --dry-run

:memo: Remember: Don't edit the vendor or node-modules folders. They are overwritten on updates.

Patched package.json to convert object to array with correct files. Be sure to update your plugin-name.php to your plugin file.

   "files": [
      "ajax/*",
      "assets/*",
      "backend/*",
      "cli/*",
      "engine/*",
      "frontend/*",
      "functions/*",
      "integrations/*",
      "internals/*",
      "languages/*",
      "rest/*",
      "templates/*",
      "vendor/*",
      "index.php",
      "LICENSE.txt",
      "plugin-name.php",
      "README.txt",
      "uninstall.php"
   ],

Libraries

These are options in wpbp.json.

ayecode/wp-super-duper
A class to build a widget, shortcode and Gutenberg block.

freemius/wordpress-sdk
Freemius truly empowers developers to create prosperous subscription-based businesses.

julien731/wp-review-me
A lightweight library to include in your WordPress theme/plugin to ask the user to review it on WordPress.org

origgami/cmb2-grid
CMB2 grid columns.

seravo/wp-custom-bulk-actions
Custom bulk actions for any type of post.

cmb2/cmb2
CMB2 is a developer's toolkit for building metaboxes, custom fields, and forms.

johnbillion/extended-cpts
A library which provides extended functionality to WordPress custom post types and taxonomies.

inpsyde/assets
A Composer package to deal with scripts and styles.

stevegrunwell/wp-cache-remember
Helper for the object cache and transients.

wpbp/cpt_columns
Improve the CPT list in the backend.

:warning: CMB2 has columns built in.

wpbp/cronplus
Add and remove cronjobs.

wpbp/debug
Query Monitor Wrapper.

wpbp/i18n-notice
Handle i18n for plugins, based on Yoast i18n-module.

wpbp/page-madness-detector
Detect if the website is using a pagebuilder/visual builder.

wpbp/pointerplus
Create a WP Admin wizard-like system.

wpbp/template
Load template files with autosearch and multilanguage folder for email template.

wpbp/widgets-helper
A class to ease creating powered Widgets.

micropackage/requirements
A requirements checker.

wpdesk/wp-notice
Library to display notices in wp-admin.

yahnis-elsts/plugin-update-checker
A custom update checker.

Tools

WPBP/tools
Bash scripts. Currently, has some for wp-bump-version and wp-readme-last-wp-tested.

CodeAtCode/freemius-suite
Suite to package and deploy the free version of the plugin by Freemius on WordPress SVN.

Snippets

:red_circle: This section requires more information about what these things do and where to find them.

backend

bubble-notification-pending-cpt
donate-link-plugin-list
block
impexp-settings

frontend

body-class
cpt-search-support
wp-localize-script
shortcode
template-system

system

capability-system
upgrade-procedure
transient
rest

Can you open a PR for the new readme? In this way we can move the discussion in a dedicated place.

About the npm commands I am talking with @erikyo and a fix is in study.
For the generator I have to think because I think that the similar issue it was in the composer.json and I fixed it.

I also realized I had to add some missing files and folders

Good catch! Actually all these folders were necessary for the default configuration of the plugin, so I updated the package.json. I also removed the "/*" which is not necessary and indeed it seemed to interfere with npm-packlist and .npmignore

There is possibly some way to ignore files but I couldn't get it to work. If they are added to .gitignore or using .npmignore files they are supposed to be ignored: https://www.npmjs.com/package/npm-packlist#user-content-interaction-between-packagejson-and-npmignore-rules

That's right! also in this case I followed your suggestion and tried to exclude the ./assets/src/* folder. Anyway i had to place an additional .npmignore inside the subfolder as specified here to get it working (cc @Mte90)

Some further changes maybe were needed to update the js code but this will fix the zip generation issue.

Awesome, thank you both!

I can make a new issue for the markdown page I posted. I didn't think it was complete though. I'm not sure what to fill in for the snippets or even if the steps are correct. Maybe it could go here too https://github.com/WPBP/WordPress-Plugin-Boilerplate-Powered/wiki

If you can do a PR with your changes we can discuss there what can be improved. In the meantime next week I will do a new generator release with some bugfixes (thanks @erikyo) like the one for the package.json.

Probably I can do also a new bboilerplate release with those npm fixes together to the generator.

Ticket closed as those issues was fixed. If @Ryvix can do a PR with the readme changes I can do a new boilerplate release with the generator with those changes.

WPBP / WordPress-Plugin-Boilerplate-Powered