docs: update documentation

Author: swashata

site/docs/apis/project-configuration.md

@@ -38,6 +38,12 @@ module.exports = {
 				main: ['./src/app/index.js'],
 				mobile: ['./src/app/mobile.js'],
 			},
+			// If enabled, all WordPress provided external scripts, including React
+			// and ReactDOM are aliased automatically. Do note that all `@wordpress`
+			// namespaced imports are automatically aliased and enqueued by the
+			// PHP library. It will not change the JSX pragma because of external
+			// dependencies.
+			optimizeForGutenberg: false,
 			// Extra webpack config to be passed directly
 			webpackConfig: undefined,
 		},
@@ -64,6 +70,10 @@ module.exports = {
 	// Project specific config
 	// Needs react?
 	hasReact: true,
+	// Whether or not to use the new jsx runtime introduced in React 17
+	// this is opt-in
+	// @see {https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html}
+	useReactJsxRuntime: false,
 	// Disable react refresh
 	disableReactRefresh: false,
 	// Needs sass?
@@ -155,17 +165,14 @@ it has to be an array of object of a certain shape. First let us see an example.
 
 ```js
 module.exports = {
-	// ...
-	// Files we need to compile, and where to put
 	files: [
-		// If this has length === 1, then single compiler
 		{
 			name: 'app',
 			entry: {
 				main: ['./src/app/index.js'],
 				mobile: ['./src/app/mobile.js'],
 			},
-			// Extra webpack config to be passed directly
+			optimizeForGutenberg: false,
 			webpackConfig: undefined,
 		},
 	],
@@ -197,7 +204,6 @@ interface EntryConfig {
 interface FileConfig {
 	name: string;
 	entry: EntryConfig;
-	typeWatchFiles?: string[];
 	hasTypeScript?: boolean;
 	webpackConfig?:
 		| webpack.Configuration
@@ -240,6 +246,17 @@ code.
 It can support both webpack configuration objects or function to get further
 control. Kindly read the [_Extending Webpack Config_](/tutorials/extending-webpack-config/) under [tutorials](/tutorials/).
 
+#### `optimizeForGutenberg` (`boolean`):
+
+_since v6.0.0_
+
+If enabled, then all of WordPress managed JavaScript files, including, React,
+ReactDOM, lodash, lodash-es, jQuery and everything under `@wordpress` namespace
+are automatically marked externals and loaded from global `wp` object.
+
+The new PHP library automatically takes care of loading those WordPress scripts
+so you don't have to do anything from your part.
+
 ##### Callback Function
 
 The most powerful form is the function. It has the following signature
@@ -291,6 +308,13 @@ You can not pass `rel/path/to/dist` here.
 
 Where you need support for react specific presets, like `jsx`.
 
+## `useReactJsxRuntime` (`boolean`):
+
+_since v6.0.0_
+
+Whether or not to use the new jsx runtime introduced in React 17. This is opt-in
+as of now. Please see [here for implications](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
+
 ## `disableReactRefresh` (`boolean`):
 
 When you have react for your project, wpackio will use react fast refresh
@@ -341,8 +365,6 @@ incorporate [react hot loader](https://github.com/gaearon/react-hot-loader).
 
 ```js
 module.exports = {
-	// ...
-	// Hook into babeloverride so that we can add react-hot-loader plugin
 	jsBabelOverride: defaults => ({
 		...defaults,
 		plugins: ['react-hot-loader/babel'],
@@ -382,7 +404,6 @@ files and reload browser on change. Useful for watching `.php` files.
 
 ```js
 module.exports = {
-	// ...
 	watch: './(inc|includes)/**/*.php',
 };
 ```

site/docs/tutorials/breaking-changes-v6.md

@@ -0,0 +1,74 @@
+---
+title: Upgrading from v5 to v6 and Breaking Changes
+order: -2
+shortTitle: Breaking v5 ➡️ v6
+---
+
+Version 6 of `@wpackio/scripts` has many improvements. While most of the changes
+are kept as backward compatible, some might break your project. So please take
+note of the followings.
+
+## POSTCSS VERSION UPDATE
+
+`postcss-loader` has been updated to the very latest and now `postcss` is a
+peer dependency. So after updating you'd either need to install `postcss`
+
+```bash
+yarn add postcss --dev
+```
+
+Or bootstrap again
+
+```bash
+yarn bootstrap
+```
+
+For CSS processing to work.
+
+## AUTOMATIC WORDPRESS SCRIPTS ALIASING
+
+> If you are not using anything from `@wordpress` package, then you are not affected.
+
+Starting v6, all modules under `@wordpress` namespace will be automatically
+marked as externals. So when you do something like
+
+```js
+import { __ } from '@wordpress/i18n';
+
+const greetings = __('Hello World', 'domain');
+```
+
+It will be roughly compiled into
+
+```js
+const { __ } = wp.i18n;
+
+const greetings = __('Hello World', 'domain');
+```
+
+But it doesn't mean you have to add `wp-i18n` script dependency manually. If you
+are using `wpackio/enqueue` PHP library, then this process is automatic. No code
+change is necessary.
+
+We do this by default only for all `@wordpress` namespace packages. We don't do
+this for React, ReactDOM, jQuery or any other scripts.
+
+Except when `optimizeForGutenberg` is set to true. Please see [Project Configuration](/apis/project-configuration/#optimizeforgutenberg-boolean) to learn more.
+
+## CHANGES IN MANIFEST
+
+> If you are not dealing with the manifest file directly, then you are not affected.
+
+webpack asset manifest plugin has been updated and it has changed the output
+format. Accordingly `wpackio/enqueue` has also been updated (`v3.0.0`). If you
+are dealing with the manifest directly, then note instead of
+
+```php
+$manifest['wpackioEp'][ $entryPoint ]
+```
+
+we now have to do
+
+```php
+$manifest['wpackioEp'][ $entryPoint ]['assets']
+```

site/docs/tutorials/updating-wpackio.md

@@ -0,0 +1,35 @@
+---
+title: Updating wpackio scripts to the latest version
+order: -1
+shortTitle: Update wpackio
+---
+
+Updating `@wpackio/scripts` and related toolchain is very straight forward and
+just like updating any other nodejs dependencies.
+
+First update the package by running
+
+```bash
+yarn upgrade-interactive --latest
+```
+
+or
+
+```bash
+yarn add @wpackio/scripts --dev
+# IF USING NPM
+npm i --save-dev @wpackio/scripts
+```
+
+This will install the latest version.
+
+Now run the following command
+
+```bash
+yarn bootstrap
+# IF USING NPM
+npm run bootstrap
+```
+
+This will check for other updates necessary and install the latest version of
+needed packages.

site/package.json

@@ -4,9 +4,9 @@
   "version": "1.0.0",
   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
   "dependencies": {
-    "@svgr/webpack": "5.4.0",
-    "bulma": "0.9.1",
-    "classnames": "2.2.6",
+    "@svgr/webpack": "5.5.0",
+    "bulma": "0.9.2",
+    "classnames": "2.3.1",
     "docsearch.js": "2.6.3",
     "gatsby": "2.27.1",
     "gatsby-image": "2.6.0",
@@ -26,8 +26,8 @@
     "gatsby-remark-smartypants": "2.5.0",
     "gatsby-source-filesystem": "2.6.1",
     "gatsby-transformer-remark": "2.11.0",
-    "node-sass": "4.14.1",
-    "prismjs": "1.22.0",
+    "node-sass": "^4.14.1",
+    "prismjs": "1.23.0",
     "prop-types": "15.7.2",
     "react": "16.14.0",
     "react-dom": "16.14.0",
@@ -46,10 +46,10 @@
   },
   "devDependencies": {
     "@wpackio/eslint-config": "file:../packages/eslint-config",
-    "eslint": "7.14.0",
+    "eslint": "7.25.0",
     "gatsby-plugin-sharp": "2.9.0",
     "gatsby-transformer-sharp": "2.7.0",
-    "prettier": "2.2.0"
+    "prettier": "2.2.1"
   },
   "repository": {
     "type": "git",