@wordpress/create-block 4.5.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +61 -65
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,18 +1,26 @@
1
1
  # Create Block
2
2
 
3
- Create Block is an officially supported tool for scaffolding WordPress plugins with blocks. It generates PHP, JS, CSS code, and everything you need to start the project. It integrates a modern build setup with no configuration.
3
+ Create Block is an **officially supported tool for scaffolding a WordPress plugin that registers a block**. It generates PHP, JS, CSS code, and everything you need to start the project. It also integrates a modern build setup with no configuration.
4
4
 
5
- It is largely inspired by [create-react-app](https://create-react-app.dev/docs/getting-started). Major kudos to [@gaearon](https://github.com/gaearon), the whole Facebook team, and the React community.
5
+ _It is largely inspired by [create-react-app](https://create-react-app.dev/docs/getting-started). Major kudos to [@gaearon](https://github.com/gaearon), the whole Facebook team, and the React community._
6
6
 
7
- ## Description
7
+ > **Blocks are the fundamental elements of modern WordPress sites**. Introduced in [WordPress 5.0](https://wordpress.org/news/2018/12/bebo/), they allow [page and post builder-like functionality](https://wordpress.org/gutenberg/) to every up-to-date WordPress website.
8
8
 
9
- Blocks are the fundamental element of the WordPress block editor. They are the primary way in which plugins can register their functionality and extend the editor's capabilities.
9
+ > _Learn more about the [Block API at the Gutenberg HandBook](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)._
10
10
 
11
- Visit the [Gutenberg handbook](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/) to learn more about Block API.
11
+ ## Table of Contents
12
+
13
+ - [Quick start](#quick-start)
14
+ - [Usage](#usage)
15
+ - [Interactive Mode](#interactive-mode)
16
+ - [`slug`](#slug)
17
+ - [`options`](#options)
18
+ - [Available Commands](#available-commands)
19
+ - [External Project Templates](#external-project-templates)
20
+ - [Contributing to this package](#contributing-to-this-package)
12
21
 
13
- ## Quick start
14
22
 
15
- You only need to provide the `slug` – the target location for scaffolded plugin files and the internal block name.
23
+ ## Quick start
16
24
 
17
25
  ```bash
18
26
  $ npx @wordpress/create-block todo-list
@@ -20,15 +28,17 @@ $ cd todo-list
20
28
  $ npm start
21
29
  ```
22
30
 
31
+ The `slug` provided (`todo-list` in the example) defines the folder name for the scaffolded plugin and the internal block name. The WordPress plugin generated must [be installed manually](https://wordpress.org/support/article/managing-plugins/#manual-plugin-installation).
32
+
33
+
23
34
  _(requires `node` version `14.0.0` or above, and `npm` version `6.14.4` or above)_
24
35
 
25
- It creates a WordPress plugin that you need to [install manually](https://wordpress.org/support/article/managing-plugins/#manual-plugin-installation).
26
36
 
27
- [Watch a video introduction to create-block on Learn.wordpress.org](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)
37
+ > [Watch a video introduction to create-block on Learn.wordpress.org](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)
28
38
 
29
39
  ## Usage
30
40
 
31
- The following command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.
41
+ The `create-block` command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.
32
42
 
33
43
  ```bash
34
44
  $ npx @wordpress/create-block [options] [slug]
@@ -36,9 +46,28 @@ $ npx @wordpress/create-block [options] [slug]
36
46
 
37
47
  ![Demo](https://user-images.githubusercontent.com/699132/103872910-4de15f00-50cf-11eb-8c74-67ca91a8c1a4.gif)
38
48
 
39
- `[slug]` is optional. When provided, it triggers the quick mode where it is used as the block slug used for its identification, the output location for scaffolded files, and the name of the WordPress plugin. The rest of the configuration is set to all default values unless overridden with some options listed below.
49
+ > The name for a block is a unique string that identifies a block. Block Names are structured as `namespace`/`slug`, where namespace is the name of your plugin or theme.
50
+
51
+ > In most cases, we recommended pairing blocks with WordPress plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.
52
+
53
+ ### Interactive Mode
54
+
55
+ When no `slug` is provided, the script will run in interactive mode and will start prompting for the input required (`slug`, title, namespace...) to scaffold the project.
56
+
57
+
58
+ ### `slug`
59
+
60
+ The use of `slug` is optional.
61
+
62
+ When provided it triggers the _quick mode_, where this `slug` is used:
63
+ - as the block slug (required for its identification)
64
+ - as the output location (folder name) for scaffolded files
65
+ - as the name of the WordPress plugin.
66
+
67
+ The rest of the configuration is set to all default values unless overridden with some options listed below.
68
+
69
+ ### `options`
40
70
 
41
- Options:
42
71
 
43
72
  ```bash
44
73
  -V, --version output the version number
@@ -55,94 +84,61 @@ Options:
55
84
  --variant choose a block variant as defined by the template
56
85
  ```
57
86
 
58
- More examples:
59
-
60
- 1. Interactive mode - without giving a project name, the script will run in interactive mode giving a chance to customize the important options before generating the files.
61
-
62
- ```bash
63
- $ npx @wordpress/create-block
64
- ```
87
+ #### `--template`
65
88
 
66
- 2. External npm package – it is also possible to select an external npm package as a template.
89
+ This argument specifies an _external npm package_ as a template.
67
90
 
68
91
  ```bash
69
92
  $ npx @wordpress/create-block --template my-template-package
70
93
  ```
71
94
 
72
- 3. Local template directory – it is also possible to pick a local directory as a template.
95
+ This argument also allows to pick a _local directory_ as a template.
73
96
 
74
97
  ```bash
75
98
  $ npx @wordpress/create-block --template ./path/to/template-directory
76
99
  ```
77
100
 
78
- 4. Generating a dynamic block based on the built-in template.
101
+ #### `--variant`
79
102
 
80
- ```bash
81
- $ npx @wordpress/create-block --variant dynamic
82
- ```
83
-
84
- 5. Help – you need to use `npx` to output usage information.
103
+ With this argument, `create-block` will generate a [dynamic block](https://developer.wordpress.org/block-editor/explanations/glossary/#dynamic-block) based on the built-in template.
85
104
 
86
105
  ```bash
87
- $ npx @wordpress/create-block --help
88
- ```
89
-
90
- 5. No plugin mode – it is also possible to scaffold only block files into the current directory.
91
-
92
- ```bash
93
- $ npx @wordpress/create-block --no-plugin
106
+ $ npx @wordpress/create-block --variant dynamic
94
107
  ```
95
108
 
96
- When you scaffold a block, you must provide at least a `slug` name, the `namespace` which usually corresponds to either the `theme` or `plugin` name. In most cases, we recommended pairing blocks with WordPress plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.
97
-
98
- ## Available Commands
109
+ #### `--help`
99
110
 
100
- When bootstrapped with the `static` template (or any other project template with `wpScripts` flag enabled), you can run several commands inside the directory:
111
+ With this argument, the `create-block` package outputs usage information.
101
112
 
102
113
  ```bash
103
- $ npm start
104
- ```
105
-
106
- Starts the build for development. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#start).
107
-
108
- ```bash
109
- $ npm run build
110
- ```
111
-
112
- Builds the code for production. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#build).
113
-
114
- ```bash
115
- $ npm run format
114
+ $ npx @wordpress/create-block --help
116
115
  ```
117
116
 
118
- Formats files. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#format).
117
+ #### `--no-plugin`
119
118
 
120
- ```bash
121
- $ npm run lint:css
122
- ```
123
-
124
- Lints CSS files. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#lint-style).
119
+ With this argument, the `create-block` package runs in _No plugin mode_ which only scaffolds block files into the current directory.
125
120
 
126
121
  ```bash
127
- $ npm run lint:js
122
+ $ npx @wordpress/create-block --no-plugin
128
123
  ```
124
+ #### `--wp-env`
129
125
 
130
- Lints JavaScript files. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#lint-js).
126
+ With this argument, the `create-block` package will add to the generated plugin the configuration and the script to run [`wp-env` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) within the plugin. This will allow you to easily set up a local WordPress environment (via Docker) for building and testing the generated plugin.
131
127
 
132
128
  ```bash
133
- $ npm run plugin-zip
129
+ $ npx @wordpress/create-block --wp-env
134
130
  ```
135
131
 
136
- Creates a zip file for a WordPress plugin. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#plugin-zip).
132
+ ## Available commands in the scaffolded project
137
133
 
138
- ```bash
139
- $ npm run packages-update
140
- ```
134
+ The plugin folder created when executing this command, is a node package with a modern build setup that requires no configuration.
141
135
 
142
- Updates WordPress packages to the latest version. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#packages-update).
136
+ A set of scripts is available from inside that folder (provided by the `scripts` package) to make your work easier. [Click here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#available-scripts) for a full description of these commands.
143
137
 
144
138
  _Note: You don’t need to install or configure tools like [webpack](https://webpack.js.org), [Babel](https://babeljs.io) or [ESLint](https://eslint.org) yourself. They are preconfigured and hidden so that you can focus on coding._
145
139
 
140
+ For example, running the `start` script from inside the generated folder (`npm start`) would automatically start the build for development.
141
+
146
142
  ## External Project Templates
147
143
 
148
144
  [Click here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/create-block/docs/external-template.md) for information on External Project Templates
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wordpress/create-block",
3
- "version": "4.5.0",
3
+ "version": "4.7.0",
4
4
  "description": "Generates PHP, JS and CSS code for registering a block for a WordPress plugin.",
5
5
  "author": "The WordPress Contributors",
6
6
  "license": "GPL-2.0-or-later",
@@ -31,7 +31,7 @@
31
31
  "wp-create-block": "./index.js"
32
32
  },
33
33
  "dependencies": {
34
- "@wordpress/lazy-import": "^1.8.0",
34
+ "@wordpress/lazy-import": "^1.10.0",
35
35
  "chalk": "^4.0.0",
36
36
  "change-case": "^4.1.2",
37
37
  "check-node-version": "^4.1.0",
@@ -48,5 +48,5 @@
48
48
  "publishConfig": {
49
49
  "access": "public"
50
50
  },
51
- "gitHead": "511f4cc1f0138641bc4394bc1cf36e833109c791"
51
+ "gitHead": "1eb65aabe6738097f4c062e78f69ae8f05879848"
52
52
  }