@wordpress/create-block 2.5.2 → 2.8.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 2.8.0 (2022-01-27)
+
+### New Features
+
+-   Integrated a new `plugin-zip` command to create a zip file for a WordPress plugin ([#37687](https://github.com/WordPress/gutenberg/pull/37687)).
+-   Add support for handling block templates with the `blockTemplatesPath` field in the external template configuration ([#37612](https://github.com/WordPress/gutenberg/pull/37612)).
+-   Add a new field `folderName` for setting the location for the `block.json` file and other optional block files generated from block templates included in the folder set with the `blockTemplatesPath` setting ([#37612](https://github.com/WordPress/gutenberg/pull/37612)).
+
+### Enhancement
+
+-   Speed up scaffolding process by omitting WordPress dependencies in the template ([#37639](https://github.com/WordPress/gutenberg/pull/37639)).
+-   Update link to block registration reference ([#37674](https://github.com/WordPress/gutenberg/pull/37674))
+
+### Internal
+
+-   The bundled `npm-package-arg` dependency has been updated from requiring `^8.0.1` to requiring `^8.1.5` ([#37395](https://github.com/WordPress/gutenberg/pull/37395)).
+
+## 2.7.0 (2021-11-07)
+
+### New Features
+
+-   Add $schema definition to generated `block.json` file.
+
+## 2.6.0 (2021-10-22)
+
+### New Features
+
+-   Add passing local directories to --template. ([#35645](https://github.com/WordPress/gutenberg/pull/35645))
+-   Add `slugPascalCase` to the list of variables that can be used in templates ([#35462](https://github.com/WordPress/gutenberg/pull/35462))
+
 ## 2.5.0 (2021-07-21)
 
 ### Enhancements

package/LICENSE.md

@@ -1,6 +1,6 @@
 ## Gutenberg
 
-    Copyright 2016-2021 by the contributors
+    Copyright 2016-2022 by the contributors
 
 **License for Contributions (on and after April 15, 2021)**
 

package/README.md

@@ -12,7 +12,7 @@ Visit the [Gutenberg handbook](https://developer.wordpress.org/block-editor/deve
 
 ## Quick start
 
-You just need to provide the `slug` which is the target location for scaffolded files and the internal block name.
+You just need to provide the `slug` which is the target location for scaffolded plugin files and the internal block name.
 
 ```bash
 $ npx @wordpress/create-block todo-list
@@ -40,10 +40,10 @@ Options:
 
 ```bash
 -V, --version                output the version number
--t, --template <name>        block template type name, allowed values: "es5", "esnext", or the name of an external npm package (default: "esnext")
+-t, --template <name>        plugin template type name, allowed values: "es5", "esnext", the name of an external npm package (default: "esnext"), or the path to a local directory.
 --namespace <value>          internal namespace for the block name
---title <value>              display title for the block
---short-description <value>  short description for the block
+--title <value>              display title for the plugin/block
+--short-description <value>  short description for the plugin/block
 --category <name>            category name for the block
 --wp-scripts                 enable integration with `@wordpress/scripts` package
 --no-wp-scripts              disable integration with `@wordpress/scripts` package
@@ -65,7 +65,13 @@ $ npx @wordpress/create-block
 $ npx @wordpress/create-block --template es5
 ```
 
-3. Help – you need to use `npx` to output usage information.
+3. Local template directory – it is also possible to pick a local directory as a template.
+
+```bash
+$ npx @wordpress/create-block --template ./path/to/template
+```
+
+4. Help – you need to use `npx` to output usage information.
 
 ```bash
 $ npx @wordpress/create-block --help
@@ -125,7 +131,21 @@ It is mandatory to provide the main file (`index.js` by default) for the package
 
 #### `templatesPath`
 
-A mandatory field with the path pointing to the location where template files live (nested folders are also supported). All files without the `.mustache` extension will be ignored.
+A mandatory field with the path pointing to the location where plugin template files live (nested folders are also supported). All files without the `.mustache` extension will be ignored.
+
+_Example:_
+
+```js
+const { join } = require( 'path' );
+
+module.exports = {
+	templatesPath: join( __dirname, 'plugin-templates' ),
+};
+```
+
+#### `blockTemplatesPath`
+
+An optional field with the path pointing to the location where template files for the individual block live (nested folders are also supported). All files without the `.mustache` extension will be ignored.
 
 _Example:_
 
@@ -133,13 +153,13 @@ _Example:_
 const { join } = require( 'path' );
 
 module.exports = {
-	templatesPath: join( __dirname, 'templates' ),
+	blockTemplatesPath: join( __dirname, 'block-templates' ),
 };
 ```
 
 #### `assetsPath`
 
-This setting is useful when your template scaffolds a block that uses static assets like images or fonts, which should not be processed. It provides the path pointing to the location where assets are located. They will be copied to the `assets` subfolder in the generated plugin.
+This setting is useful when your template scaffolds a plugin that uses static assets like images or fonts, which should not be processed. It provides the path pointing to the location where assets are located. They will be copied to the `assets` subfolder in the generated plugin.
 
 _Example:_
 
@@ -147,7 +167,7 @@ _Example:_
 const { join } = require( 'path' );
 
 module.exports = {
-	assetsPath: join( __dirname, 'assets' ),
+	assetsPath: join( __dirname, 'plugin-assets' ),
 };
 ```
 
@@ -171,6 +191,7 @@ module.exports = {
 
 The following configurable variables are used with the template files. Template authors can change default values to use when users don't provide their data:
 
+-   `$schema` (default: `https://schemas.wp.org/trunk/block.json`)
 -   `apiVersion` (default: `2`) - see https://make.wordpress.org/core/2020/11/18/block-api-version-2/.
 -   `slug` (no default)
 -   `namespace` (default: `'create-block'`)
@@ -186,7 +207,8 @@ The following configurable variables are used with the template files. Template
 -   `version` (default: `'0.1.0'`)
 -   `wpScripts` (default: `true`)
 -   `wpEnv` (default: `false`)
--   `npmDependencies` (default: `[]`) – the list of remote npm packages to be installed in the project with [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install).
+-   `npmDependencies` (default: `[]`) – the list of remote npm packages to be installed in the project with [`npm install`](https://docs.npmjs.com/cli/v8/commands/npm-install) when `wpScripts` is enabled.
+-   `folderName` (default: `.`) – the location for the `block.json` file and other optional block files generated from block templates included in the folder set with the `blockTemplatesPath` setting.
 -   `editorScript` (default: `'file:./build/index.js'`)
 -   `editorStyle` (default: `'file:./build/index.css'`)
 -   `style` (default: `'file:./build/style-index.css'`)

package/lib/index.js

@@ -14,7 +14,7 @@ const log = require( './log' );
 const { engines, version } = require( '../package.json' );
 const scaffold = require( './scaffold' );
 const {
-	getBlockTemplate,
+	getPluginTemplate,
 	getDefaultValues,
 	getPrompts,
 } = require( './templates' );
@@ -34,13 +34,16 @@ program
 	.arguments( '[slug]' )
 	.option(
 		'-t, --template <name>',
-		'block template type name, allowed values: "es5", "esnext", or the name of an external npm package',
+		'plugin template type name, allowed values: "es5", "esnext", or the name of an external npm package',
 		'esnext'
 	)
 	.option( '--namespace <value>', 'internal namespace for the block name' )
-	.option( '--title <value>', 'display title for the block' )
+	.option( '--title <value>', 'display title for the plugin/block' )
 	// The name "description" is used internally so it couldn't be used.
-	.option( '--short-description <value>', 'short description for the block' )
+	.option(
+		'--short-description <value>',
+		'short description for the plugin/block'
+	)
 	.option( '--category <name>', 'category name for the block' )
 	.option(
 		'--wp-scripts',
@@ -66,8 +69,8 @@ program
 		) => {
 			await checkSystemRequirements( engines );
 			try {
-				const blockTemplate = await getBlockTemplate( templateName );
-				const defaultValues = getDefaultValues( blockTemplate );
+				const pluginTemplate = await getPluginTemplate( templateName );
+				const defaultValues = getDefaultValues( pluginTemplate );
 				const optionsValues = pickBy(
 					{
 						category,
@@ -88,16 +91,16 @@ program
 						title: startCase( slug ),
 						...optionsValues,
 					};
-					await scaffold( blockTemplate, answers );
+					await scaffold( pluginTemplate, answers );
 				} else {
-					const prompts = getPrompts( blockTemplate ).filter(
+					const prompts = getPrompts( pluginTemplate ).filter(
 						( { name } ) =>
 							! Object.keys( optionsValues ).includes( name )
 					);
 					log.info( '' );
-					log.info( "Let's customize your block:" );
+					log.info( "Let's customize your WordPress plugin:" );
 					const answers = await inquirer.prompt( prompts );
-					await scaffold( blockTemplate, {
+					await scaffold( pluginTemplate, {
 						...defaultValues,
 						...optionsValues,
 						...answers,

package/lib/{init-block-json.js → init-block.js}

@@ -2,15 +2,18 @@
  * External dependencies
  */
 const { omitBy } = require( 'lodash' );
-const { join } = require( 'path' );
+const { dirname, join } = require( 'path' );
+const makeDir = require( 'make-dir' );
 const { writeFile } = require( 'fs' ).promises;
 
 /**
  * Internal dependencies
  */
 const { info } = require( './log' );
+const { writeOutputTemplate } = require( './output' );
 
-module.exports = async ( {
+async function initBlockJSON( {
+	$schema,
 	apiVersion,
 	slug,
 	namespace,
@@ -22,18 +25,22 @@ module.exports = async ( {
 	supports,
 	dashicon,
 	textdomain,
+	folderName,
 	editorScript,
 	editorStyle,
 	style,
-} ) => {
-	const outputFile = join( process.cwd(), slug, 'block.json' );
+} ) {
 	info( '' );
 	info( 'Creating a "block.json" file.' );
+
+	const outputFile = join( process.cwd(), slug, folderName, 'block.json' );
+	await makeDir( dirname( outputFile ) );
 	await writeFile(
 		outputFile,
 		JSON.stringify(
 			omitBy(
 				{
+					$schema,
 					apiVersion,
 					name: namespace + '/' + slug,
 					version,
@@ -54,4 +61,19 @@ module.exports = async ( {
 			'\t'
 		)
 	);
+}
+
+module.exports = async function ( outputTemplates, view ) {
+	await Promise.all(
+		Object.keys( outputTemplates ).map(
+			async ( outputFile ) =>
+				await writeOutputTemplate(
+					outputTemplates[ outputFile ],
+					join( view.folderName, outputFile ),
+					view
+				)
+		)
+	);
+
+	await initBlockJSON( view );
 };

package/lib/init-package-json.js

@@ -40,15 +40,16 @@ module.exports = async ( {
 					format: 'wp-scripts format',
 					'lint:css': 'wp-scripts lint-style',
 					'lint:js': 'wp-scripts lint-js',
-					start: 'wp-scripts start',
 					'packages-update': 'wp-scripts packages-update',
+					'plugin-zip': 'wp-scripts plugin-zip',
+					start: 'wp-scripts start',
 				},
 			},
 			isEmpty
 		)
 	);
 
-	if ( size( npmDependencies ) ) {
+	if ( wpScripts && size( npmDependencies ) ) {
 		info( '' );
 		info(
 			'Installing npm dependencies. It might take a couple of minutes...'

package/lib/output.js

@@ -0,0 +1,28 @@
+/**
+ * External dependencies
+ */
+const { dirname, join } = require( 'path' );
+const makeDir = require( 'make-dir' );
+const { render } = require( 'mustache' );
+const { writeFile } = require( 'fs' ).promises;
+
+const writeOutputAsset = async ( inputFile, outputFile, view ) => {
+	const outputFilePath = join( view.slug, 'assets', outputFile );
+	await makeDir( dirname( outputFilePath ) );
+	writeFile( outputFilePath, inputFile );
+};
+
+const writeOutputTemplate = async ( inputFile, outputFile, view ) => {
+	// Output files can have names that depend on the slug provided.
+	const outputFilePath = join(
+		view.slug,
+		outputFile.replace( /\$slug/g, view.slug )
+	);
+	await makeDir( dirname( outputFilePath ) );
+	writeFile( outputFilePath, render( inputFile, view ) );
+};
+
+module.exports = {
+	writeOutputAsset,
+	writeOutputTemplate,
+};

package/lib/scaffold.js

@@ -1,24 +1,22 @@
 /**
  * External dependencies
  */
-const { writeFile } = require( 'fs' ).promises;
-const { snakeCase } = require( 'lodash' );
-const makeDir = require( 'make-dir' );
-const { render } = require( 'mustache' );
-const { dirname, join } = require( 'path' );
+const { snakeCase, camelCase, upperFirst } = require( 'lodash' );
 
 /**
  * Internal dependencies
  */
-const initBlockJSON = require( './init-block-json' );
+const initBlock = require( './init-block' );
 const initPackageJSON = require( './init-package-json' );
 const initWPScripts = require( './init-wp-scripts' );
 const initWPEnv = require( './init-wp-env' );
 const { code, info, success } = require( './log' );
+const { writeOutputAsset, writeOutputTemplate } = require( './output' );
 
 module.exports = async (
-	blockTemplate,
+	{ blockOutputTemplates, outputTemplates, outputAssets },
 	{
+		$schema,
 		apiVersion,
 		namespace,
 		slug,
@@ -35,6 +33,7 @@ module.exports = async (
 		wpScripts,
 		wpEnv,
 		npmDependencies,
+		folderName,
 		editorScript,
 		editorStyle,
 		style,
@@ -44,15 +43,16 @@ module.exports = async (
 	namespace = namespace.toLowerCase();
 
 	info( '' );
-	info( `Creating a new WordPress block in "${ slug }" folder.` );
+	info( `Creating a new WordPress plugin in "${ slug }" folder.` );
 
-	const { outputTemplates, outputAssets } = blockTemplate;
 	const view = {
+		$schema,
 		apiVersion,
 		namespace,
 		namespaceSnakeCase: snakeCase( namespace ),
 		slug,
 		slugSnakeCase: snakeCase( slug ),
+		slugPascalCase: upperFirst( camelCase( slug ) ),
 		title,
 		description,
 		dashicon,
@@ -66,34 +66,36 @@ module.exports = async (
 		textdomain: slug,
 		wpScripts,
 		npmDependencies,
+		folderName,
 		editorScript,
 		editorStyle,
 		style,
 	};
+
 	await Promise.all(
-		Object.keys( outputTemplates ).map( async ( outputFile ) => {
-			// Output files can have names that depend on the slug provided.
-			const outputFilePath = join(
-				slug,
-				outputFile.replace( /\$slug/g, slug )
-			);
-			await makeDir( dirname( outputFilePath ) );
-			writeFile(
-				outputFilePath,
-				render( outputTemplates[ outputFile ], view )
-			);
-		} )
+		Object.keys( outputTemplates ).map(
+			async ( outputFile ) =>
+				await writeOutputTemplate(
+					outputTemplates[ outputFile ],
+					outputFile,
+					view
+				)
+		)
 	);
 
 	await Promise.all(
-		Object.keys( outputAssets ).map( async ( outputFile ) => {
-			const outputFilePath = join( slug, 'assets', outputFile );
-			await makeDir( dirname( outputFilePath ) );
-			writeFile( outputFilePath, outputAssets[ outputFile ] );
-		} )
+		Object.keys( outputAssets ).map(
+			async ( outputFile ) =>
+				await writeOutputAsset(
+					outputAssets[ outputFile ],
+					outputFile,
+					view
+				)
+		)
 	);
 
-	await initBlockJSON( view );
+	await initBlock( blockOutputTemplates, view );
+
 	await initPackageJSON( view );
 
 	if ( wpScripts ) {

package/lib/templates/es5/$slug.php.mustache

@@ -25,7 +25,7 @@
  * Registers all block assets so that they can be enqueued through the block editor
  * in the corresponding context.
  *
- * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/applying-styles-with-stylesheets/
+ * @see https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/applying-styles-with-stylesheets/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
 	$dir = __DIR__;

package/lib/templates/es5/readme.txt.mustache

@@ -3,7 +3,7 @@
 Contributors:      {{author}}
 {{/author}}
 Tags:              block
-Tested up to:      5.8.0
+Tested up to:      5.9
 Stable tag:        {{version}}
 {{#license}}
 License:           {{license}}

package/lib/templates/esnext/{$slug.php.mustache → plugin/$slug.php.mustache}

@@ -26,9 +26,9 @@
  * Behind the scenes, it registers also all assets so they can be enqueued
  * through the block editor in the corresponding context.
  *
- * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
+ * @see https://developer.wordpress.org/reference/functions/register_block_type/
  */
 function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
-	register_block_type( __DIR__ );
+	register_block_type( __DIR__ . '/build' );
 }
 add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );

package/lib/templates/esnext/{.gitignore.mustache → plugin/.gitignore.mustache}

@@ -20,8 +20,11 @@ node_modules/
 # Optional eslint cache
 .eslintcache
 
-# Output of 'npm pack'
+# Output of `npm pack`
 *.tgz
 
+# Output of `wp-scripts plugin-zip`
+*.zip
+
 # dotenv environment variables file
 .env

package/lib/templates/esnext/{readme.txt.mustache → plugin/readme.txt.mustache}

@@ -3,7 +3,7 @@
 Contributors:      {{author}}
 {{/author}}
 Tags:              block
-Tested up to:      5.8.0
+Tested up to:      5.9
 Stable tag:        {{version}}
 {{#license}}
 License:           {{license}}

package/lib/templates.js

@@ -3,6 +3,8 @@
  */
 const { command } = require( 'execa' );
 const glob = require( 'fast-glob' );
+const { resolve } = require( 'path' );
+const { existsSync } = require( 'fs' );
 const { mkdtemp, readFile } = require( 'fs' ).promises;
 const { fromPairs, isObject } = require( 'lodash' );
 const npmPackageArg = require( 'npm-package-arg' );
@@ -17,7 +19,7 @@ const CLIError = require( './cli-error' );
 const { info } = require( './log' );
 const prompts = require( './prompts' );
 
-const predefinedBlockTemplates = {
+const predefinedPluginTemplates = {
 	es5: {
 		defaultValues: {
 			slug: 'es5-example',
@@ -42,13 +44,13 @@ const predefinedBlockTemplates = {
 			supports: {
 				html: false,
 			},
-			npmDependencies: [
-				'@wordpress/block-editor',
-				'@wordpress/blocks',
-				'@wordpress/i18n',
-			],
+			folderName: 'src',
+			editorScript: 'file:./index.js',
+			editorStyle: 'file:./index.css',
+			style: 'file:./style-index.css',
 		},
-		templatesPath: join( __dirname, 'templates', 'esnext' ),
+		templatesPath: join( __dirname, 'templates', 'esnext', 'plugin' ),
+		blockTemplatesPath: join( __dirname, 'templates', 'esnext', 'block' ),
 	},
 };
 
@@ -102,6 +104,7 @@ const externalTemplateExists = async ( templateName ) => {
 
 const configToTemplate = async ( {
 	assetsPath,
+	blockTemplatesPath,
 	defaultValues = {},
 	templatesPath,
 } ) => {
@@ -110,20 +113,26 @@ const configToTemplate = async ( {
 	}
 
 	return {
+		blockOutputTemplates: blockTemplatesPath
+			? await getOutputTemplates( blockTemplatesPath )
+			: {},
 		defaultValues,
 		outputAssets: assetsPath ? await getOutputAssets( assetsPath ) : {},
 		outputTemplates: await getOutputTemplates( templatesPath ),
 	};
 };
 
-const getBlockTemplate = async ( templateName ) => {
-	if ( predefinedBlockTemplates[ templateName ] ) {
+const getPluginTemplate = async ( templateName ) => {
+	if ( predefinedPluginTemplates[ templateName ] ) {
 		return await configToTemplate(
-			predefinedBlockTemplates[ templateName ]
+			predefinedPluginTemplates[ templateName ]
 		);
 	}
 
 	try {
+		if ( existsSync( resolve( templateName ) ) ) {
+			return await configToTemplate( require( resolve( templateName ) ) );
+		}
 		return await configToTemplate( require( templateName ) );
 	} catch ( error ) {
 		if ( error instanceof CLIError ) {
@@ -137,8 +146,8 @@ const getBlockTemplate = async ( templateName ) => {
 
 	if ( ! ( await externalTemplateExists( templateName ) ) ) {
 		throw new CLIError(
-			`Invalid block template type name: "${ templateName }". Allowed values: ` +
-				Object.keys( predefinedBlockTemplates )
+			`Invalid plugin template type name: "${ templateName }". Allowed values: ` +
+				Object.keys( predefinedPluginTemplates )
 					.map( ( name ) => `"${ name }"` )
 					.join( ', ' ) +
 				', or an existing npm package name.'
@@ -168,7 +177,7 @@ const getBlockTemplate = async ( templateName ) => {
 			throw error;
 		} else {
 			throw new CLIError(
-				`Invalid block template downloaded. Error: ${ error.message }`
+				`Invalid plugin template downloaded. Error: ${ error.message }`
 			);
 		}
 	} finally {
@@ -178,8 +187,9 @@ const getBlockTemplate = async ( templateName ) => {
 	}
 };
 
-const getDefaultValues = ( blockTemplate ) => {
+const getDefaultValues = ( pluginTemplate ) => {
 	return {
+		$schema: 'https://schemas.wp.org/trunk/block.json',
 		apiVersion: 2,
 		namespace: 'create-block',
 		category: 'widgets',
@@ -190,15 +200,16 @@ const getDefaultValues = ( blockTemplate ) => {
 		wpScripts: true,
 		wpEnv: false,
 		npmDependencies: [],
+		folderName: '.',
 		editorScript: 'file:./build/index.js',
 		editorStyle: 'file:./build/index.css',
 		style: 'file:./build/style-index.css',
-		...blockTemplate.defaultValues,
+		...pluginTemplate.defaultValues,
 	};
 };
 
-const getPrompts = ( blockTemplate ) => {
-	const defaultValues = getDefaultValues( blockTemplate );
+const getPrompts = ( pluginTemplate ) => {
+	const defaultValues = getDefaultValues( pluginTemplate );
 	return Object.keys( prompts ).map( ( promptName ) => {
 		return {
 			...prompts[ promptName ],
@@ -208,7 +219,7 @@ const getPrompts = ( blockTemplate ) => {
 };
 
 module.exports = {
-	getBlockTemplate,
+	getPluginTemplate,
 	getDefaultValues,
 	getPrompts,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/create-block",
-	"version": "2.5.2",
+	"version": "2.8.0",
 	"description": "Generates PHP, JS and CSS code for registering a block for a WordPress plugin.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -31,22 +31,22 @@
 		"wp-create-block": "./index.js"
 	},
 	"dependencies": {
-		"@wordpress/lazy-import": "^1.3.2",
+		"@wordpress/lazy-import": "^1.4.0",
 		"chalk": "^4.0.0",
 		"check-node-version": "^4.1.0",
 		"commander": "^4.1.0",
 		"execa": "^4.0.2",
-		"fast-glob": "^2.2.7",
+		"fast-glob": "^3.2.7",
 		"inquirer": "^7.1.0",
 		"lodash": "^4.17.21",
 		"make-dir": "^3.0.0",
 		"mustache": "^4.0.0",
-		"npm-package-arg": "^8.0.1",
+		"npm-package-arg": "^8.1.5",
 		"rimraf": "^3.0.2",
 		"write-pkg": "^4.0.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "8f7f052bc04e3f4eb50f479ced14be1489b9fa79"
+	"gitHead": "d95ccb9366e249133cdb1d7b25c382446b9ee502"
 }