Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Create Block] Allow explicit target for block creation #44717

Open
colorful-tones opened this issue Oct 5, 2022 · 17 comments · May be fixed by #53781
Open

[Create Block] Allow explicit target for block creation #44717

colorful-tones opened this issue Oct 5, 2022 · 17 comments · May be fixed by #53781
Assignees
Labels
Developer Experience Ideas about improving block and theme developer experience [Package] Create Block /packages/create-block [Status] In Progress Tracking issues with work in progress [Type] Enhancement A suggestion for improvement.

Comments

@colorful-tones
Copy link
Member

colorful-tones commented Oct 5, 2022

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 colorful-tones added [Package] Create Block /packages/create-block Developer Experience Ideas about improving block and theme developer experience labels Oct 5, 2022
@colorful-tones colorful-tones self-assigned this Oct 5, 2022
@colorful-tones
Copy link
Member Author

Likely related to #25188

@ryanwelcher
Copy link
Contributor

ryanwelcher commented Oct 5, 2022

@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
Copy link
Member Author

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
Copy link
Member Author

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

@gziolo
Copy link
Member

gziolo commented Oct 13, 2022

@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:

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
Copy link

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
Copy link

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
Copy link
Contributor

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
Copy link

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
Copy link
Contributor

ryanwelcher commented Nov 14, 2022

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
Copy link
Contributor

ryanwelcher commented Nov 14, 2022

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

@afmarchetti
Copy link

@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:

Schermata 2022-11-14 alle 13 57 54

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
Copy link
Contributor

carolinan commented Feb 6, 2023

+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.

@jordesign jordesign added the [Type] Enhancement A suggestion for improvement. label Aug 2, 2023
@github-actions github-actions bot added the [Status] In Progress Tracking issues with work in progress label Aug 17, 2023
@bacoords
Copy link
Contributor

bacoords commented Dec 4, 2023

+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
Copy link
Member

gziolo commented Dec 5, 2023

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

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

@ryanwelcher
Copy link
Contributor

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

@bacoords
Copy link
Contributor

bacoords commented Dec 5, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Developer Experience Ideas about improving block and theme developer experience [Package] Create Block /packages/create-block [Status] In Progress Tracking issues with work in progress [Type] Enhancement A suggestion for improvement.
Projects
None yet
8 participants