Skip to content

Commit

Permalink
docs: update website
Browse files Browse the repository at this point in the history
  • Loading branch information
swashata committed Jul 27, 2021
1 parent 8d6be75 commit 73e1702
Show file tree
Hide file tree
Showing 58 changed files with 1,509 additions and 900 deletions.
2 changes: 2 additions & 0 deletions site/.eslintrc
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
{
"root": true,
"extends": "@wpackio/eslint-config",
"rules": {
"prettier/prettier": "off",
"react/jsx-filename-extension": "off",
"react/prop-types": "off",
"import/prefer-default-export": "off",
Expand Down
3 changes: 3 additions & 0 deletions site/.prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.cache/
public/
package.json
3 changes: 2 additions & 1 deletion site/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
This website is live under [https://wpack.io](https://wpack.io).

Made with [GatsbyJS](https://www.gatsbyjs.org/) and hosted with [Netlify](https://www.netlify.com/).
Made with [GatsbyJS](https://www.gatsbyjs.org/) and hosted with
[Netlify](https://www.netlify.com/).
69 changes: 33 additions & 36 deletions site/docs/apis/node-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@ shortTitle: Nodejs API
While `@wpackio/scripts` is meant to be used as a CLI tool, it does expose all
of the necessary node.js APIs to create your own CLI.

For now, the best place to check the exports is [the file](https://github.com/swashata/wp-webpack-script/blob/master/packages/scripts/src/index.ts) itself. Since we
develop in typescript and ship all `.d.ts` files, you will get IDE intellisense
by default.
For now, the best place to check the exports is
[the file](https://github.com/swashata/wp-webpack-script/blob/master/packages/scripts/src/index.ts)
itself. Since we develop in typescript and ship all `.d.ts` files, you will get
IDE intellisense by default.

Here are the documentation for a few APIs which are useful.

Expand Down Expand Up @@ -80,18 +81,21 @@ interface PresetOptions {
}
```

More information can be found in the [source repository](https://github.com/swashata/wp-webpack-script/tree/master/packages/babel-preset-base).
More information can be found in the
[source repository](https://github.com/swashata/wp-webpack-script/tree/master/packages/babel-preset-base).

#### `typeChecker`

Whether to include preset for `'flow'` or `'typescript'`. Leave `undefined` to ignore both.
Whether to include preset for `'flow'` or `'typescript'`. Leave `undefined` to
ignore both.

Possible values are `'flow'`, `'typescript'` or `undefined`.

## `getDefaultBabelPresetOptions`

Get default options for [@wpackio/babel-preset-base](https://github.com/swashata/wp-webpack-script/tree/master/packages/babel-preset-base) considering whether project
has react and whether it is in development mode.
Get default options for
[@wpackio/babel-preset-base](https://github.com/swashata/wp-webpack-script/tree/master/packages/babel-preset-base)
considering whether project has react and whether it is in development mode.

### Usage

Expand Down Expand Up @@ -125,10 +129,7 @@ module.exports = {
loader: 'babel-loader',
options: {
presets: getBabelPresets(
getDefaultBabelPresetOptions(
true,
isDev
),
getDefaultBabelPresetOptions(true, isDev),
undefined
),
},
Expand All @@ -150,15 +151,17 @@ module.exports = {
## `getFileLoaderOptions`

Get options for file-loader. This takes into account the application directory,
development or production mode and public path for file-loader usage from css files.
development or production mode and public path for file-loader usage from css
files.

If you want to use `file-loader` for your own custom asset management, then
do use this API for dynamically setting the option. This ensures a few things, like
If you want to use `file-loader` for your own custom asset management, then do
use this API for dynamically setting the option. This ensures a few things, like

1. All assets are put inside `assets` directory.
2. Assets works for CSS files where relative path is necessary.

More information can be found in [`file-loader` tutorial](/tutorials/using-file-loader/).
More information can be found in
[`file-loader` tutorial](/tutorials/using-file-loader/).

### Usage

Expand All @@ -184,11 +187,7 @@ module.exports = {
use: [
{
loader: 'file-loader',
options: getFileLoaderOptions(
appDir,
isDev,
false
),
options: getFileLoaderOptions(appDir, isDev, false),
},
],
},
Expand Down Expand Up @@ -218,13 +217,15 @@ Whether or not to set publicPath for `file-loader`, depending on `isDev`.

## `issuer`

The API consists a family of [`webpack issuer`](https://webpack.js.org/configuration/module/#ruleissuer) utilities. Use them in conjunction with [`file-loader`](/tutorials/using-file-loader/) or
`url-loader`.
The API consists a family of
[`webpack issuer`](https://webpack.js.org/configuration/module/#ruleissuer)
utilities. Use them in conjunction with
[`file-loader`](/tutorials/using-file-loader/) or `url-loader`.

- `issuerForNonStyleFiles`: Tests if files are not, `css`, `sass` and `scss`.
- `issuerForStyleFiles`: Tests if files are one of `css`, `sass` or `scss`.
- `issuerForNonJsTsFiles`: Tests if files are not, `js`, `jsx`, `ts` and `tsx`.
- `issuerForJsTsFiles`: Tests if files are one of `js`, `jsx`, `ts` and `tsx`.
- `issuerForNonStyleFiles`: Tests if files are not, `css`, `sass` and `scss`.
- `issuerForStyleFiles`: Tests if files are one of `css`, `sass` or `scss`.
- `issuerForNonJsTsFiles`: Tests if files are not, `js`, `jsx`, `ts` and `tsx`.
- `issuerForJsTsFiles`: Tests if files are one of `js`, `jsx`, `ts` and `tsx`.

### Usage

Expand Down Expand Up @@ -255,11 +256,7 @@ module.exports = {
use: [
{
loader: 'file-loader',
options: getFileLoaderOptions(
appDir,
isDev,
false
),
options: getFileLoaderOptions(appDir, isDev, false),
},
],
},
Expand All @@ -275,8 +272,8 @@ module.exports = {

## `loader`

When you want to extend webpack config you might run into issues when
specifying loaders directly like
When you want to extend webpack config you might run into issues when specifying
loaders directly like

```js
const module = {
Expand All @@ -291,9 +288,9 @@ const module = {
};
```

The above is would throw error saying, could not resolve `file-loader`. To
ease up sharing loaders across configuration, `@wpackio/scripts` expose
the following loaders.
The above is would throw error saying, could not resolve `file-loader`. To ease
up sharing loaders across configuration, `@wpackio/scripts` expose the following
loaders.

```js
const {
Expand Down
86 changes: 48 additions & 38 deletions site/docs/apis/php-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ order: 3
shortTitle: PHP API
---

The following are the methods and options for [`\WPackio\Enqueue`](<(https://packagist.org/packages/wpackio/enqueue)>)
class which comes with the composer package.
The following are the methods and options for
[`\WPackio\Enqueue`](<(https://packagist.org/packages/wpackio/enqueue)>) class
which comes with the composer package.

## Creating Instance

Expand All @@ -28,7 +29,8 @@ It has to be same as you have defined in `wpackio.project.js` under `appName`.

#### `$outputPath` (`string`)

It has to be same as you have defined in `wpackio.project.js` under `outputPath`.
It has to be same as you have defined in `wpackio.project.js` under
`outputPath`.

#### `$version` (`string`)

Expand All @@ -40,18 +42,19 @@ Either `"plugin"` or "`theme`", depending on your project.

#### `$pluginPath` (`string`|`false`)

Absolute path to the main plugin file. If you are using it for `theme`, then don't
pass it, or just use `false`.
Absolute path to the main plugin file. If you are using it for `theme`, then
don't pass it, or just use `false`.

#### `$themeType` (`string`)

Defaults to `"regular"`. If you are applying this to a child theme, then make the value `"child"`.
Defaults to `"regular"`. If you are applying this to a child theme, then make
the value `"child"`.

## Instance API: `getAssets`

Get handle and Url of all assets from the entry-point.
It doesn't enqueue anything for you, rather returns an associative array
with handles and urls. You should use it to enqueue it on your own.
Get handle and Url of all assets from the entry-point. It doesn't enqueue
anything for you, rather returns an associative array with handles and urls. You
should use it to enqueue it on your own.

### Usage

Expand Down Expand Up @@ -170,14 +173,14 @@ $config = [
];
```

> **NOTE**: The `identifier` property was removed from `$config`. We need complete
> control of the script `handle` to make sure common chunks, such as, `runtime`
> is enqueued only once.
> **NOTE**: The `identifier` property was removed from `$config`. We need
> complete control of the script `handle` to make sure common chunks, such as,
> `runtime` is enqueued only once.
### Return `array`

It returns an associative array with `js` and `css` asset handles and URLs
for ready consumption using `wp_enqueue` API. A return may look like this
It returns an associative array with `js` and `css` asset handles and URLs for
ready consumption using `wp_enqueue` API. A return may look like this

```php
$return = [
Expand All @@ -204,13 +207,13 @@ $return = [
];
```

It doesn't take care of internal dependencies by itself. The `register`
method does.
It doesn't take care of internal dependencies by itself. The `register` method
does.

## Instance API: `register`

Register script handles with WordPress for an entrypoint inside a source.
It does not enqueue the assets, just calls `wp_register_*` on the asset.
Register script handles with WordPress for an entrypoint inside a source. It
does not enqueue the assets, just calls `wp_register_*` on the asset.

This is useful if just registering script for things like gutenberg.

Expand All @@ -235,7 +238,8 @@ $assets = $enqueue->register( 'app', 'main', [

All the assets within an `$entryPoint` has internal dependency upon each other.

Let us consider the following `manifest.json` file generated by `@wpackio/scripts`.
Let us consider the following `manifest.json` file generated by
`@wpackio/scripts`.

```json
{
Expand Down Expand Up @@ -268,20 +272,20 @@ Here the asset `app/main.js` of `main` `entryPoint` depends on both
1. `app/vendor~main.js`.
2. `app/runtime.js`.

So if we were to `enqueue` only `app/main.js` it will not work, it need the
two scripts in the page too.
So if we were to `enqueue` only `app/main.js` it will not work, it need the two
scripts in the page too.

Similarly for the asset `app/mobile.js`, of `mobile` `entryPoint`, we have
internal dependency of

1. `app/vendor~mobile.js`.
2. `app/runtime.js`.

Here `app/runtime.js` is a common dependency for both the entry-points. But
we should enqueue it only once.
Here `app/runtime.js` is a common dependency for both the entry-points. But we
should enqueue it only once.

To make sure WordPress properly enqueues the dependencies and doesn't come
up with duplicate scripts, `register` sets the scripts dependencies for you.
To make sure WordPress properly enqueues the dependencies and doesn't come up
with duplicate scripts, `register` sets the scripts dependencies for you.

So if you do something like this

Expand All @@ -302,11 +306,12 @@ wp_enqueue_script(
);
```

You can be assured that `app/vendor~main.js` and `app/runtime.js` will both
be enqueued.
You can be assured that `app/vendor~main.js` and `app/runtime.js` will both be
enqueued.

There isn't any magic behind it. We just set internal dependencies during
call to [`wp_register_(script|style)`](https://github.com/swashata/wpackio-enqueue/blob/6411c4781ed58e62f746e01d081fd1838a212edf/inc/Enqueue.php#L146).
There isn't any magic behind it. We just set internal dependencies during call
to
[`wp_register_(script|style)`](https://github.com/swashata/wpackio-enqueue/blob/6411c4781ed58e62f746e01d081fd1838a212edf/inc/Enqueue.php#L146).

## Instance API: `enqueue`

Expand Down Expand Up @@ -360,16 +365,19 @@ $enqueue->getManifest( $name );

#### `$name` (`string`)

The name of the file entry as defined in `**wpackio.project.js**`. The `wpackio-scripts`
internally creates a directory of the same name inside `outputPath`.
The name of the file entry as defined in `**wpackio.project.js**`. The
`wpackio-scripts` internally creates a directory of the same name inside
`outputPath`.

`wpackio/enqueue` uses the same concept and looks for a file `manifest.json` inside
the same directory and returns the content as an associative array (using `json_decode`).
`wpackio/enqueue` uses the same concept and looks for a file `manifest.json`
inside the same directory and returns the content as an associative array (using
`json_decode`).

## Instance API: `getUrl`

Get public URL of an asset (script or style). It doesn't check whether the asset
actually exists or not. It just calculates the plugin/theme URL from `$outputPath`.
actually exists or not. It just calculates the plugin/theme URL from
`$outputPath`.

This is meant to be used to get URL from `manifest.json` files directly.

Expand All @@ -392,12 +400,13 @@ $enqueue->getManifest( $asset );

#### `$asset` (`string`)

The relative path of the asset (with forward `/` as director separator) for which
URL is to be calculated.
The relative path of the asset (with forward `/` as director separator) for
which URL is to be calculated.

## Instance API: `getPrimaryJsHandle`

Get primary js handle from enqueued/registered assets. This is useful to localize/translate the script handle.
Get primary js handle from enqueued/registered assets. This is useful to
localize/translate the script handle.

### Usage

Expand All @@ -421,7 +430,8 @@ Assets array as returned from enqueue or register.

## Instance API: `getPrimaryCssHandle`

Get primary css handle from enqueued/registered assets. This is useful to localize/translate the script handle.
Get primary css handle from enqueued/registered assets. This is useful to
localize/translate the script handle.

### Usage

Expand Down
Loading

0 comments on commit 73e1702

Please sign in to comment.