[Create Block] Allow explicit target for block creation

[colorful-tones]

What problem does this address?

I love that the @wordpress/create-block package allows the user to scaffold out a plugin for their blocks and even has templates to allow developers to extend and create their own block template packages. ❤️ ❤️ 🤯

I believe it is a high-priority need for developers to be able to create this type of structure in their plugin to support multiple blocks:

my-block-plugin/
    my-block-plugin.php
    src/
        block-one/
            block.json
        block-two/
            block.json
    build/
        block-one/
            block.json
        block-two/
            block.json

One can technically accomplish this with @wordpress/create-block as it stands, but there are a few awkward steps to get there, which hinder its overall potential.

To achieve that structure, you have to: npx @wordpress/create-block my-block-plugin, which outputs:

my-block-plugin/
    my-block-plugin.php
    src/
        block.json <-- no nesting in sub-directory
    build/
        block.json <-- no nesting in sub-directory

Now, you must manually move the src/block.json into a unique block directory: src/block-one/block.json, or delete it and run @wordpress/create-block again in another directory and with the --no-plugin flag.

Proposed solution: add --target flag

We add an optional flag for --target, which would allow developers to pass a block target within the .src/, e.g. --target block-one/, which would result in: src/block-one/block.json. If no --target then the slug should be the fallback used to create the target directory. Then, npx @wordpress/create-block block-one would result in the creation of src/block-one/block.json still.

These changes would allow builders to run the following and have a plugin:

npx @wordpress/create-block my-block-plugin
cd my-block-plugin
rm -i src/*
npx @wordpress/create-block block-one --target block-one/ --no-plugin

and get the following:

my-block-plugin/
    my-block-plugin.php
    src/
        block-one/
            block.json

[colorful-tones]

Likely related to #25188

[ryanwelcher]

@colorful-tones thank you for taking the time to put this together with such detail! Here are my thoughts.

For example, it can be confusing and contrary to encourage builders to create a plugin with create-block but also have a flag --no-plugin. Just the name alone: create-block can be confusing in conveying the use case: you can also create a plugin (for your block).

The original purpose of the package is to create a plugin that contains a block. That’s the recommended way to create blocks and how they need to be packaged to be submitted to the plugin repo.

The --no-plugin flag was added to provide some more flexibility to block developers who were asking for the ability to scaffold just the block to an existing block plugin. I think the confusion that you mention is dependent on how to think about creating blocks, we need a plugin scaffolded to contain any number of blocks. Without that baseline, blocks are not registered, so IMO that should be the primary function of the tool.

Adding the --no-plugin flag makes it feel like creating blocks is a secondary thought. This is awkward and greatly hinders this package's potential.

In this case, creating the block is secondary because we already have the plugin scaffolded and we only need to scaffold new block files.

Proposed solution 1: rename --no-plugin to --plugin

This would fundamentally change the default behavior of the package from scaffolding a full plugin with a single block to only scaffolding the block files. For users new to the tool or using the tool to learn block development, that would be an extremely frustrating and confusing experience as it would produce files that essentially do nothing on their own. IMO, the default behavior ( which is a new plugin with a block ) should not require a flag to take place. That feels like a bad developer experience to me.

.. it would allow builders to run the following and have a plugin and multiple blocks ready to go: npx @wordpress/create-block --plugin my-block-plugin && npx @wordpress/create-block block-one && npx @wordpress/create-block block-two and get the following

Without flag change, these commands would be very similar. Beyond saving a few keystrokes, I don't see a huge benefit here.

npx @wordpress/create-block my-block-plugin && npx @wordpress/create-block block-one --no-plugin && npx @wordpress/create-block block-two --no-plugin

There have also been some discussions ( I can't find the issue - @gziolo? ) around providing a way to generate multiple blocks at once as well by passing a list of names - which would simplify this command even more ie.:
npx @wordpress/create-block my-block-plugin && npx @wordpress/create-block block-one, block-two, block-three --no-plugin

Propose solution 2: add --block-target flag

This is a great idea. Being able to target where the block is scaffolded in either mode of the package is great idea. Currently, the src directory can be customized by templates ( using folderName ) but that is ignored when in --no-plugin mode to allow using different templates ( which may define folderName differently ). Having a --target flag would be helpful in this case.

[colorful-tones]

The original purpose of the package is to create a plugin that contains a block. That’s the recommended way to create blocks and how they need to be packaged to be submitted to the plugin repo.

I agree and understand this premise, but quickly get hung up on the fact that it is called @wordpress/create-block and not @wordpress/create-block-plugin. Since, primarily it is initially used to create a WordPress plugin that has a block. In foresight, it might have been best to have two separate packages: @wordpress/create-block and @wordpress/create-block-plugin. The later would likely reference the other as a dependency.

This is a great idea. Being able to target where the block is scaffolded in either mode of the package is great idea. Currently, the src directory can be customized by templates ( using folderName ) but that is ignored when in --no-plugin mode to allow using different templates ( which may define folderName differently ). Having a --target flag would be helpful in this case.

I'm going to take a pass at editing and refining this Issue's current proposal to streamline to solely this feature request, as I do think it would be beneficial. Thanks for all the insight and feedback @ryanwelcher

[colorful-tones]

Ok, I've streamlined the proposed solution. The initial one was too broad. Thanks.

[gziolo]

@colorful-tones, thank you for opening this issue and making the effort to explain your use case. I agree that it would be great to have more control over where to create the block. Initially, we didn't have any way to distinguish what belongs to the block and what is part of the plugin or project. We changed that a few months back in the anticipation to add support even for multiple blocks. As of today, you can override where to put block-related templates with:

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

Line 229 in 9dc7f9d

folderName: './src',

It's too simple for now and it doesn't support anything that would make the path dynamic, but we could add a special case like:

folderName: 'src/$block-slug',

and the dynamically replace $block-slug with the value provided by the user. We do a similar trick for the plugin slug used in the name of the file, example: $slug.php.mustache.

To support multiple blocks in Create Block, we might also need to introduce the distinction between the plugin slug and the block slug, because each block needs an unique name. It's all doable and part of the discussion we had in #25188.

[iamleese]

I agree with @colorful-tones in regards to the structure in the initial installation having nested sub-directories in the src directory. However, I think it should be achieved in one command rather than multiple lines :

npx @wordpress/create-block my-plugin-name --block-name={my-block-slug}

Without a block-name flag could just be the default installation.

I also agree with @ryanwelcher that semantically, the additional "--no-plugin" / "--plugin" flags might cause confusion and is unnecessary.

I'm all for ease-of-use and clarity. It seems like the immediate need is to have better documentation on how to structure the directory to accommodate multiple blocks.

[afmarchetti]

All the WordPress dev want to create block with php, js, css whitout npm and build worflow.
In a small business web site we haven't the time and budget to create a block with that system (local build) to make small changes, we need something quick and easy like this:
https://blockstudio.dev/

If you make something like this all the community will love Gutenberg and WordPress again.

This could change everything and make full site editing grow fast, think about that.

I went to WordCamp Italy, yesterday and all the devs agree with that, cheers keep the good :)

[ryanwelcher]

All the WordPress dev want to create block with php, js, css whitout npm and build worflow.

It is entirely possible to create a custom block without a build process now. You can scaffold a block using the es5 template with the create-block tool - npx @wordpress/create-block block-with-no-build -template es5

[afmarchetti]

Ok but we still need node and a local environment, right?
We just want open a js-php-css file and make changes as a normal template / plugin...

[ryanwelcher]

Ok but we still need node and a local environment, right?

You don't need node to build the block, there is no build process using the es5 template. You will need npx available to run the create-block tool but that is also optional as you can manually create the files you need.

As for a local environment, typically you'd want to have a local WordPress installation set up and running to test your code changes, is that what you're referring to?

[ryanwelcher]

@afmarchetti you can have a look at these examples in the Gutenberg Examples repo for blocks without a build process.

[afmarchetti]

@ryanwelcher thanks :-) i tried and test the example here (recipe block):
https://github.com/WordPress/gutenberg-examples/blob/trunk/blocks-non-jsx/05-recipe-card/block.js

it's a lot of code to create such a simple html structure, in block studio you can do something like this to create block templates:

Every WordPress dev will love a solution like this, quick, easy, simple.

I know that is not super easy create a solution like this, but this type of development experience will solve a lot of problems of wp devs community and definitely unlock the power of Gutenberg...

Thanks for your time

[carolinan]

+1 for making it easier to create plugins with more than one block. I don't think the majority creates blocks with the purpose of submitting single block plugins to the wordpress.org plugin directory.

[bacoords]

+1 to this. My current workflow is constantly cd back and forth between my src directory and root plugin directory every time I add a new block. It'd be create it it could scaffold the block in a sub-directory and it (seems like?) this --target parameter would help?

[gziolo]

@ryanwelcher opened some time ago a PR that implements the requested feature:

• Create Block: Adds --target-dir flag to allow the tool to target where to scaffold #53781

Would that solve the issue for you? The PR mostly needs some testing and I can help with reviewing the code if necessary.

[ryanwelcher]

I can update the PR to address the merge conflicts. Be happy to get this merged.

[bacoords]

Thanks @ryanwelcher @gziolo - I tested it and added a few comments.