How to use and create template for @wordpress/create-block --template command?

[tresorama]

When scaffolding a new Block we have the option to select a template to use for the process.

Docs says that we can use a template when invoking the cli like:

npx @wordpress/create-block --template TEMPLATE_REF_GOES_HERE

I have a series of question that i think is good to make clear also for other devs.

1. Where is a list of official template (if any) ?
2. Where is a list of community template (if any) ?
3. How to create a own local template ?
   The docs says that we can do npx @wordpress/create-block --template /absolute-path/in-my/local/pc
   How this differs from copy paste ?
   Do i need to "prepare" something in my controlled directory to make the cli happy ?
4. How to create a own remote template ?
   4.1
   Is it possible to donpx @wordpress/create-block --template NAME_OF_NPM_PACKAGE ?
   If yes, there is a "starter repo" with all thing already ready to publish to npm ?
   4.2
   And npx @wordpress/create-block --template PUBLIC_GITHUB_REPO_URL ?
   If yes, there are some specific requirements?

Resources
https://developer.wordpress.org/block-editor/getting-started/create-block
https://www.npmjs.com/package/@wordpress/create-block

[gziolo]

@juanmaguitar and @ryanwelcher, it looks like there is some gap in the documentation for Create Block regarding how to consume custom templates.

[juanmaguitar]

Hi @tresorama!
Thanks for these questions and feedback.

Where is a list of official templates (if any) ? Where is a list of community template (if any)?

There's no list of official templates as there are no many "official templates"
@ryanwelcher suggested the idea of providing a place where the community could add their templates so the existing ones can be located from a centralized place

How to create your own local template ?

The documentation about External Project Templates is here: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/
Is there some info you're missing from this page?

Some examples of templates can be found at:

• https://github.com/WordPress/gutenberg/tree/trunk/packages/create-block-interactive-template
• https://github.com/WordPress/gutenberg/tree/trunk/packages/create-block-tutorial-template
• https://github.com/wptrainingteam/wp-block-development-examples/tree/trunk/templates/block-examples/templates

How to create your own remote template ?

Templates can be published as NPM packages so they can easily accessed from the CLI.
For example, the create-block-interactive-template has been published in NPM so it can be used from anywhere just by doing

npx  @wordpress/create-block --template @wordpress/create-block-interactive-template

Is it possible to donpx @wordpress/create-block --template NAME_OF_NPM_PACKAGE ?
If yes, there is a "starter repo" with everything already ready to publish to npm ?

Yes! But there's no "starter repo". Maybe an option could be added to create-block to scaffold a template for create-block?

And npx @wordpress/create-block --template PUBLIC_GITHUB_REPO_URL ?
If yes, there are some specific requirements?

I think this is not possible for the time being but could be a nice addition.

Please, feel free to open an issue for specific improvements in tools and/or documentation.
I also encourage you to take the lead in these changes if you're up to it. I'll be happy to provide support during this process.

[gziolo]

This is the way templates gets installed to the temporary folder:

gutenberg/packages/create-block/lib/templates.js

Lines 195 to 201 in bc704e1

	info( 'Downloading template files. It might take some time...' );
	tempCwd = await mkdtemp( join( tmpdir(), 'wp-create-block-' ) );
	await command( `npm install ${ templateName } --no-save`, {
	cwd: tempCwd,
	} );

npm install that is used there is very flexible and it supports many formats:

npm install [<package-spec> ...]

A package is:

a) a folder containing a program described by a package.json file
b) a gzipped tarball containing (a)
c) a url that resolves to (b)
d) a @ that is published on the registry (see registry) with (c)
e) a @ (see npm dist-tag) that points to (d)
f) a that has a "latest" tag satisfying (e)
g) a that resolves to (a)

More details at https://docs.npmjs.com/cli/v10/commands/npm-install. I see examples for git, GitHub, gist, Bitbucket, etc.